Strawman: add sameAs property to __Type to announce mapping/equality to other schemas/types

[saerdnaer]

related to w3c/graphql-rdf#4

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: saerdnaer / name: Andi Hubel (37690b7, a4dc2f5)

[netlify]

✅ Deploy Preview for graphql-spec-draft ready!

Name	Link
🔨 Latest commit	a4dc2f5
🔍 Latest deploy log	https://app.netlify.com/sites/graphql-spec-draft/deploys/641adcc877a10300082e50d1
😎 Deploy Preview	https://deploy-preview-1022--graphql-spec-draft.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[benjie]

Hi @saerdnaer; maybe you want to bring this to a WG meeting for discussion? https://github.com/graphql/graphql-wg/tree/main/agendas/2023

[saerdnaer]

@benjie Sure, I will try to attend on Sept. 7 – but might be in a train with possibly bad internet connection... we will see. graphql/graphql-wg#1374
Otherwise I will join a later WG meeting.

[netlify]

✅ Deploy Preview for graphql-spec-draft ready!

Name	Link
🔨 Latest commit	37690b7
🔍 Latest deploy log	https://app.netlify.com/projects/graphql-spec-draft/deploys/68df90134777b30008aa64c1
😎 Deploy Preview	https://deploy-preview-1022--graphql-spec-draft.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[benjie]

I know you proposed this for object types, but I feel this could be broadened to increase value. E.g. rather than being "same as" perhaps it could be "conforms to"? This would be particularly valuable for custom scalars, e.g.

scalar Name
  # Treat Name as a String
  @conformsTo(url: "https://spec.graphql.org/September2025/#sec-String")
  # Note it's also a schema.org Name
  @conformsTo(url: "https://schema.org/name")
  # Note it's ALSO a GraphQL Name (i.e. constrained string)
  @conformsTo(url: "https://spec.graphql.org/September2025/#Name")

One potential issue with this framing is the input/output tension; e.g. on output it's fine to just treat it as an arbitrary string - you'll only get string values from it. But on input all of the constraints apply, so you can't send any arbitrary string value - the value you send must be /^[A-Za-z_][A-Za-z0-9_]*$/ to comply with GraphQL Name. I think this is okay (and probably desired!) though.

For object types, if it conforms to something I think that means it implements at least the specified fields, but that it may additionally implement additional fields. I also think that this is probably better suited to a GraphQL interface - the object implements the interface, and the interface conforms to the requirements of the external URL. Though in your case, you literally want identity with an external type, so perhaps it's not quite right... 🤔

[saerdnaer]

In the linked example I only wanted to specify that Item in the local schema is semantically the same as https://schema.org/PodcastEpisode – this does not mean that all attributes in both classes / types are name identical.

type Item @conformsTo(uri: "https://schema.org/PodcastEpisode", mapping: EXACT) {
  id: ID!
  …
} 

Maybe we should define one build-in directive + introspection property which works of all kind of GraphQL Base Entities, and maybe add a second optional parameter which clarifies how deep the relationship goes / both match with each other. For example, during working on LinkML schema, I came across following definitions:

• exact: external concepts, predicates, or properties which are considered to be exact mappings to the class [or type] being defined.
  • These indicate semantic equivalence.
• close: external concepts, predicates, or properties that are considered to be close mappings (similar but not fully identical).
  • Used when the match is strong but slightly looser than exact.
• narrow: external concepts, predicates, or properties which are narrower in scope than the class [or type] being defined.
  • Narrow mappings are more restrictive. If modeled, they would be children of the broader concept (e.g., same as).
• broad: external concepts, predicates, or properties which are broader in scope than the class [or type] being defined.
  • Broad mappings are more general. If modeled, they would be parents of the narrower concept (e.g., in complex with).
• related: external concepts, predicates, or properties that are related in meaning but not strictly broader, narrower, or exact.
  • Indicates semantic relatedness without strong hierarchical or equivalence implications.

scalar Name
  # Treat Name as a String
  @conformsTo(url: "https://spec.graphql.org/September2025/#sec-String")
  # Note it's also a schema.org Name
  @conformsTo(url: "https://schema.org/name", mapping: EXACT)

[For other readers: You might also have a look at the parallel, more SDL driven, discussion in w3c/graphql-rdf/issues/4 ]

[saerdnaer]

@benjie Should I try to join the GraphQL WG meeting on Thursday 19:30 CET to discuss this further?