Skip to content

Provide guidance on $id keyword #158

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Provide guidance on $id keyword #158

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -213,7 +213,7 @@ Despite these potential benefits, these keywords should be omitted:
* The titles of `object` and `enum` types produced by code generation tools should be defined using key values in [$defs](https://json-schema.org/understanding-json-schema/structuring#defs). Setting the `title` keyword introduces multiple sources of truth and possible conflict.
* As described in [description generation](./CONTRIBUTING.md#description-generation), we use a different mechanism to describe the semantics of types and properties. Setting the `description` keyword introduces multiple sources of truth and possible conflict.

## Schemas and subschemas
## Schemas, subschemas, and $id

In JSON Schema, a [schema](https://json-schema.org/learn/glossary#schema) is a document, and a [subschema](https://json-schema.org/learn/glossary#subschema) is contained in surrounding parent schema. Subschemas can be nested in various ways:

Expand Down Expand Up @@ -256,6 +256,10 @@ Or a property can reference a subschema residing in a schema document's [$defs](

In order to promote stylistic consistency and allow for reuse of concepts, `object` and `enum` types should be defined in either as a top level schema document or as a subschema in a schema document's `$defs`.

Each schema has an optional [`$id`](https://json-schema.org/understanding-json-schema/basics#declaring-a-unique-identifier) defining a unique identifier for the schema. Schemas and subschemas can be referenced in other schemas using the [`$ref`](https://json-schema.org/understanding-json-schema/structuring#dollarref) keyword, which resolves against the schema's [base URI](https://json-schema.org/understanding-json-schema/structuring#base-uri) (i.e. the `$id` of the top level schema document) using [JSON pointer](https://json-schema.org/understanding-json-schema/structuring#json-pointer) syntax.

All top level schema documents should contain a `$id` field following the form `https://opentelemetry.io/otelconfig/<name>.json`. Subschemas nested in `$defs` should not include an `$id`, and should be resolved using `$ref`s relative to their top level schema document.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we have a version identifier in this path?


## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)
Expand Down
Loading