Schema metadata: what should it be?

This is the forum for Murmurations.network

Schema metadata: what should it be?

wu-lee

The example schemas all contain a metadata section, naming authors, URLs, versions etc.

This doesn't seem to be defined as part of the JSON-Schema standard draft-06. Is there a specification, or a guide, for what content is expected in the metadata object? The meaning and content of these fields can be guessed at but more explicit guidance as to the syntax and semantics would be helpful.

Specifically:

Is version expected to be an integer, or a real number, or can it be a dotted string like "1.3.0"?
Is version enforced or otherwise used for anything?

olisb

Hi - good questions, sorry this was not more clear - you are helping us write better docs 😉

The Metadata section is not 'standard' JSON schema but the idea is to use this section to provide more detail about the context of Murmurations schemas.

So Creator name and url should be the name of the person / Org creating the schema and a url which someone could visit to find out more about you / your Org. e.g.

metadata": { "creator": { "name": "Murmurations Network", "url": "https://murmurations.network/" },

The name should be the name of your schema, using underscores, appended with a hyphenated version number as an integer, so e.g. name-v1, or solidarity_economy_schema-v1

Purpose and url are more detail about the objective of your schema and a url which someone can visit to find out more detail about the specific schema e.g.

"schema": {
  "name": "test_schema-v1",
  "version": 1,
  "purpose": "A test schema to present profiles on the test map.",
  "url": "https://murmurations.network/schemas/test_schema"
}`

wu-lee Specifically:
Is version expected to be an integer, or a real number, or can it be a dotted string like "1.3.0"?

An integer

Is version enforced or otherwise used for anything?

It's not enforced, but the idea is to increment it every time you make a change to your schema. The point is to avoid making breaking changes within the same version number, so the safest way to do it is to increment it whenever a change is made. Even just changing the spelling of a data field is a breaking change.

Please ensure that the version number is incremented each time a schema or field is updated. This is especially important for fields in particular since multiple schemas will be relying on previous versions.

Hope this helps 🙂

olisb

Hello again,
We've had more chats about the metadata version number - and realised semver may be a better solution, so (I'm sorry but) my answer above is no longer correct (as I said, you are helping us improve 😉 )
So the revised answer to:

wu-lee Is version expected to be an integer, or a real number, or can it be a dotted string like "1.3.0"?

is YES.

The idea is to use versions numbers as per the format: major.minor.patch e.g. my_schema-v1.1.1.json
with only the major version changes introducing backwards-incompatible changes to the schema.

Breaking change would be anything that could cause data that was valid against the previous version to be invalid against the new version (eg. smaller max size, removed enum values, more restrictive regex pattern, new required fields).

Regarding minor and patches, our thought is that a minor change could be any non-breaking change that affects the data (or potential data) in any way (eg new non-required fields, additional enum values, etc.), and a patch would be a change to parts of the schema that don't change the data, such as rewording field descriptions (presuming the meaning of the field stays equivalent), schema annotations, re-ordering fields, or moving fields between the library and the schema itself (eg, moving a field definition out of the schema and into the library).

So file names should also be updated accordingly:

The name should be the name of your schema, using underscores, appended with a hyphenated version number as per semver, e.g. my_schema-v1.1.1.json, or solidarity_economy_schema-v1.1.1.json

This is not implemented in the existing schemas (except the not-yet-published ecovillage schema), but I will create an issue and update the existing schemas accordingly.

Sorry to mess you around but we think this will be the best way to handle file names and version numbers going forward.

Oli

wu-lee

Thanks, that is helpful

wu-lee

No problem - I've just revised my pull request accordingly.

This is the forum for Murmurations.network