What's the difference between SupergraphSdl and ServiceDefinition?

I’m working on set up schema register for apollo federation. After reading code, I find there are two input for federation gateway schema loading federation/index.ts at main · apollographql/federation · GitHub. Wondering whether we have docs document the difference?

Both serviceList and supergraphSdl (which are mutually exclusive; you only need to define one of the two) are used for local composition (serviceList) or running from a static supergraph artifact (supergraphSdl), respectfully. By and large, we are generally steering folks off serviceList since it does actual runtime federated introspection of subgraphs in order to compose the supergraph and this can be somewhat fraught (e.g., during subgraph deployment flapping if they’re running behind a load-balancer). Generally speaking, we recommend supergraphSdl over serviceList these days.

The static contents passed to supergraphSdl can be generated entirely locally (i.e., with rover supergraph compose — which still supports federated introspection but does so with intention and at the user-specified time) or pulled from the Studio registry (i.e., with rover supergraph fetch). Neither of these modes offer automatic schema rollover today, though we can imagine a way to enable a way to do this with supergraphSdl in the future.

If you desire your Gateway to automatically roll over when new supergraphs are pushed and composed in the Studio registry, you only need to provide an APOLLO_KEY environment variable (and you may optionally provide APOLLO_GRAPH_VARIANT). Neither serviceList or supergraphSdl need to be provided in this automatic mode and this is arguably our favorite mode these days since it still provides the single source of truth and offers automatic schema rollover.

All of this is probably better documented than I’ve written here in the Federation Quickstart Guide, which talks about both Local schema composition (Part 1 of the Quickstart) and Composition in Apollo Studio (Part 2).

I hope this helps!