search

graphql / composite-schemas-spec

MIT License
30 stars 9 forks source link

Minor editorial to overview #18

Closed benjie closed 8 months ago

benjie commented 9 months ago

"that which" is more suitable for a formal specification versus "what".

spec-md doesn't support linking to plurals, so references must be singular.

We shouldn't embed references for the same term multiple times in the same paragraph.

bignimbus commented 9 months ago

@benjie can you help me understand the spec-md linking a bit more? Would it be possible, for example, to define schemas as a separate keyword, defined as the plural of schema? I think it could have enough technical meaning in this context to merit an explicit definition. Not a strongly-held opinion though

benjie commented 9 months ago

@bignimbus have a read of https://spec-md.com/#sec-Definitions

We avoid plurals in the spec proper; note that definitions are incorporated as part of the prose of the spec (they’re only special in the markdown, not in the output), so defining that “source schemas” is the plural of “source schema” would be a bit weird for someone to read.