Schema versioning vs. API versioning
These are two different jobs, owned by two different parties.
GRCSchema.org tracks schema versions: every Thing carries a schemaVersion, and the registry entry for the Thing is the authority on what each version contains (see Standard Elements). API versions belong to the ISV serving the data. GRCSchema.org never dictates how a vendor versions their API, and a vendor's API version never changes what a schema means.
The recommended pattern: version by API key
Our recommendation for ISVs: tie API versions to API keys rather than minting versioned URLs. The key a client authenticates with routes them to the version they expect. Three things fall out of that:
- Clients migrate by getting a new key, not by rewriting every URL in their integration.
- The producer controls exactly who is on which version, and can see it, because keys are issued per consumer.
- Breaking changes roll out gradually. Old keys keep working against the old behavior while new keys get the new one.
URL-versioned APIs (/api/v1/...) are common and workable, and some APIs serving GRCSchema data run that way today. The key-based pattern is still the one we recommend for new builds: it keeps version negotiation in the credential, where the producer can manage it per consumer, instead of in the URL, where every client has to chase it.
Declaring the schema version in the document
Whichever way the API is versioned, the JSON-LD document itself declares which schema version it complies with:
{
"@context": "https://grcschema.org",
"@type": "Thing",
"schemaVersion": 1,
"name": "Example Thing"
}
If an ISV also wants to declare their own API version in the payload, a custom property (e.g. apiVersion) in their API context is the right place for it. That property belongs to the vendor's context, not to GRCSchema.org: the two version numbers answer different questions, and conflating them is how integrations end up pinned to the wrong thing.