The foundational utilities for operating on JSON Schema documents across dialects. More...
Typedefs | |
| using | sourcemeta::core::SchemaDependencyCallback = std::function<void(const SchemaDependency &)> |
| using | sourcemeta::core::SchemaResolverResult |
| using | sourcemeta::core::SchemaResolver = std::function<SchemaResolverResult(std::string_view)> |
| using | sourcemeta::core::SchemaWalker |
Functions | |
| SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto | sourcemeta::core::schema_resolver (const std::string_view identifier) -> SchemaResolverResult |
| SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto | sourcemeta::core::schema_is_known (const std::string_view identifier) noexcept -> bool |
| SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto | sourcemeta::core::schema_is_official (const std::string_view identifier) noexcept -> bool |
| SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto | sourcemeta::core::schema_walker (const std::string_view keyword, const SchemaVocabularies &vocabularies) -> const SchemaWalkerResult & |
| SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto | sourcemeta::core::schema_reidentify (sourcemeta::core::JSON &schema, std::string_view new_identifier, const SchemaWalker &walker, const SchemaResolver &resolver, std::string_view default_dialect="") -> void |
| SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto | sourcemeta::core::schema_identifier_keyword (const SchemaBaseDialect base_dialect) -> std::string_view |
| SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto | sourcemeta::core::schema_reidentify (sourcemeta::core::JSON &schema, std::string_view new_identifier, const SchemaBaseDialect base_dialect) -> void |
| SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto | sourcemeta::core::schema_format (sourcemeta::core::JSON &schema, const SchemaFrame &frame) -> void |
| SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto | sourcemeta::core::schema_bundle (sourcemeta::core::JSON &schema, const SchemaWalker &walker, const SchemaResolver &resolver, std::string_view default_dialect="", std::string_view default_id="", const SchemaBundleOptions &options={}) -> std::uint64_t |
| SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto | sourcemeta::core::schema_bundle (const sourcemeta::core::JSON &schema, const SchemaWalker &walker, const SchemaResolver &resolver, std::string_view default_dialect="", std::string_view default_id="", const SchemaBundleOptions &options={}) -> sourcemeta::core::JSON |
| SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto | sourcemeta::core::schema_dependencies (const sourcemeta::core::JSON &schema, const SchemaWalker &walker, const SchemaResolver &resolver, const SchemaDependencyCallback &callback, const SchemaDependenciesOptions &options={}) -> std::uint64_t |
The foundational utilities for operating on JSON Schema documents across dialects.
This module is not a JSON Schema evaluator and does not aim to become one. It offers the building blocks that any operation on a schema needs, independently of what that operation is: identification, dialect and vocabulary detection, resolution of remote schemas, keyword classification across dialects, framing a schema into the locations and references it declares, reporting what a schema depends on, and bundling a schema into a self-contained document. Evaluation is only one of the consumers of these utilities, alongside linting, transformation, code generation, and documentation tooling.
This functionality is included as follows:
| struct sourcemeta::core::SchemaBundleOptions |
Everything bundling takes beyond the schema and how to read it
Public Types | |
|---|---|
| enum class | Mode : std::uint8_t { NonOfficialMetaschemas , References } |
| The strategies that the bundling process can follow. More... | |
| using | Callback |
Public Attributes | |
| Mode | mode {Mode::NonOfficialMetaschemas} |
| The strategy to follow. | |
| std::optional< sourcemeta::core::Pointer > | default_container {} |
| Where to embed what bundling pulls in. | |
| SchemaFrame::Paths | paths {sourcemeta::core::EMPTY_WEAK_POINTER} |
| The paths to bundle within a schema wrapper. | |
| std::string_view | default_base {} |
| std::uint64_t | max_locations {std::numeric_limits<std::uint64_t>::max()} |
| Callback | callback {} |
A callback to report which schema got embedded and where, as the identifier that schema answers to and a pointer from the root of the schema being bundled. A schema that declares one of its own answers to that rather than to whichever URI it was resolved by, which are not always the same. The two are given separately because bundling picks a key that is free rather than one that matches, so the last token of that pointer is not always the identifier either
|
strong |
The strategies that the bundling process can follow.
| Callback sourcemeta::core::SchemaBundleOptions::callback {} |
A callback to report where each schema got embedded, which is the only way to know what a later call has to frame when bundling into a container that the dialect does not otherwise traverse
| std::string_view sourcemeta::core::SchemaBundleOptions::default_base {} |
The base URI that the document was retrieved from, which a relative reference within any of the given paths resolves against. As with sourcemeta::core::SchemaFrame, this does not claim that the document declares an identifier, so bundling never writes it into the document
| std::uint64_t sourcemeta::core::SchemaBundleOptions::max_locations {std::numeric_limits<std::uint64_t>::max()} |
The maximum number of frame locations that analysis may register. How many schemas bundling ends up embedding follows from what the resolver hands back rather than from the schema the caller passed in, and every frame that bundling constructs spends from this one limit, throwing sourcemeta::core::SchemaFrameLimitError once it runs out. Note that a remote is copied out of the resolver before anything charges for it, so this bounds how many oversized schemas get copied rather than whether one does
| struct sourcemeta::core::SchemaDependency |
A reference that a schema makes to a schema of another document. Several of them may name one document, as what is reported is where a reference sits rather than what analysis had to fetch. Whatever a member of this carries points into something that analysis owns for no longer than the call that reports it, so a callback that keeps any of them past its own return has to copy them out
Public Attributes | |
|---|---|
| std::string_view | origin |
| std::string_view | destination |
| The identifier of the document that the reference leads to. | |
| const sourcemeta::core::JSON * | document |
| const sourcemeta::core::JSON* sourcemeta::core::SchemaDependency::document |
The schema that the identifier was resolved to, which is there only where this is the reference that had analysis resolve it. Analysis lets go of what it read as soon as it is done with it, so a reference that reaches a document it already read, or that names what the caller says it holds, or that nothing answers for yet, carries nothing here
| std::string_view sourcemeta::core::SchemaDependency::origin |
The identifier that the document making the reference goes by, which for a document the walk read is the URI it was asked for, and for the one analysis started from is the identifier it declares, or the name the caller gave it, or nothing at all
| struct sourcemeta::core::SchemaDependenciesOptions |
Everything dependency analysis takes beyond the schema and how to read it. As with sourcemeta::core::SchemaFrame, the dialect and the paths are read for as long as analysis runs, so the caller owns them across the call, while the identifier and the base are copied
Public Types | |
|---|---|
| using | AccountedPredicate = std::function<bool(std::string_view)> |
| A predicate to ask whether the caller already accounts for a URI. | |
| using | AccountedCallback = std::function<void(std::string_view)> |
| A callback to report every URI that analysis comes to account for. | |
| using | UnresolvedCallback = std::function<void(const SchemaDependency &)> |
| A callback to report every reference that nothing came to answer for. | |
Public Attributes | |
| std::string_view | default_dialect {} |
| The dialect to assume for a schema that declares none. | |
| std::string_view | default_id {} |
| SchemaFrame::Paths | paths {sourcemeta::core::EMPTY_WEAK_POINTER} |
| std::string_view | default_base {} |
| std::uint64_t | max_locations {std::numeric_limits<std::uint64_t>::max()} |
| AccountedPredicate | accounted {} |
| UnresolvedCallback | unresolved {} |
| AccountedCallback | accounted_callback {} |
| AccountedPredicate sourcemeta::core::SchemaDependenciesOptions::accounted {} |
Whether the caller already accounts for a URI, which analysis asks before reading the document a reference names and again before deciding that a reference leads nowhere. Answering yes for one keeps the document it names from being fetched or read, while the references naming it are reported as any other, carrying nothing to fetch, so a caller answers for what it holds rather than for what it would rather analysis left alone. A dialect that a document declares is asked of the resolver by the framing that reading takes, which happens before any of this, so answering yes for one does not keep it from being resolved
| AccountedCallback sourcemeta::core::SchemaDependenciesOptions::accounted_callback {} |
Reports every URI that analysis comes to account for, whether it is one a dependency was reported for or one a document it read answers to of its own. A caller that walks several documents of one span keeps what this hands back and answers the predicate above from it, so that a document any of them reaches is read once and a reference that a document any of them read answers to settles for all of them
| std::string_view sourcemeta::core::SchemaDependenciesOptions::default_base {} |
The base URI that the document was retrieved from, which a relative reference within any of the given paths resolves against. As with sourcemeta::core::SchemaFrame, this does not claim that the document declares an identifier
| std::string_view sourcemeta::core::SchemaDependenciesOptions::default_id {} |
The identifier to assume for a schema that declares none, which names the whole document and so has no meaning where the paths below name anything other than the top of it. A wrapper takes the base below instead
| std::uint64_t sourcemeta::core::SchemaDependenciesOptions::max_locations {std::numeric_limits<std::uint64_t>::max()} |
The maximum number of frame locations that analysis may register. How many schemas analysis ends up reading follows from what the resolver hands back rather than from the schema the caller passed in, and every frame that analysis constructs spends from this one limit, throwing sourcemeta::core::SchemaFrameLimitError once it runs out. Note that a document is read in full before anything charges for it, and that what a document costs to walk follows its size rather than how many locations it registers, so this bounds how many oversized schemas get read rather than whether one does. Bounding the size of a document remains the caller's to do
| SchemaFrame::Paths sourcemeta::core::SchemaDependenciesOptions::paths {sourcemeta::core::EMPTY_WEAK_POINTER} |
The paths to analyse within a schema wrapper. Every one of them must name a schema of the document, and passing paths that repeat or that sit inside one another is undefined behaviour. Naming a path puts everything outside it out of scope, so an identifier or a dialect that a schema enclosing it declares counts for nothing, and each path is read as a schema in its own right against the base and the dialect given here
| UnresolvedCallback sourcemeta::core::SchemaDependenciesOptions::unresolved {} |
Reports every reference that nothing came to answer for, each of them where it sits, just before analysis ends over the first of them. The error that ends analysis names one of those references and nothing of the rest, and analysis lets go of all of them as it unwinds, so this is the only place they can be read. A caller that walks several documents of one span wants them, as it may still come to hold what they name. Analysis that ends over anything else reports nothing here, as whatever it reached for then is no reference of a document
| class sourcemeta::core::SchemaError |
An error that represents a general schema error event
Public Member Functions | |
|---|---|
| SchemaError (const StaticString message) noexcept | |
| Create a general schema error. | |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
Additional Inherited Members | |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
| class sourcemeta::core::SchemaResolutionError |
An error that represents a schema resolution failure event
Public Member Functions | |
|---|---|
| SchemaResolutionError (const StaticString message, const std::string_view identifier) | |
| Create a schema resolution error. | |
| auto | identifier () const noexcept -> std::string_view |
| The identifier that could not be resolved. | |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
Additional Inherited Members | |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
| class sourcemeta::core::SchemaRelativeMetaschemaResolutionError |
An error that represents a relative meta-schema resolution failure event Relative references to meta-schemas are invalid as per the specification See https://json-schema.org/draft/2020-12/json-schema-core#section-8.1.1-2
Public Member Functions | |
|---|---|
| SchemaRelativeMetaschemaResolutionError (const std::string_view identifier) | |
| Create a relative meta-schema resolution error. | |
| Public Member Functions inherited from sourcemeta::core::SchemaResolutionError | |
| SchemaResolutionError (const StaticString message, const std::string_view identifier) | |
| Create a schema resolution error. | |
| auto | identifier () const noexcept -> std::string_view |
| The identifier that could not be resolved. | |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
Additional Inherited Members | |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
| class sourcemeta::core::SchemaVocabularyError |
An error that represents a schema vocabulary error
Public Member Functions | |
|---|---|
| SchemaVocabularyError (const StaticString message, const std::string_view uri) | |
| Create a vocabulary error. | |
| auto | uri () const noexcept -> std::string_view |
| The vocabulary that caused the error. | |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
Additional Inherited Members | |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
| class sourcemeta::core::SchemaReferenceError |
An error that represents a schema resolution failure event
Public Member Functions | |
|---|---|
| SchemaReferenceError (const StaticString message, const std::string_view identifier, sourcemeta::core::Pointer schema_location) | |
| Create a reference error. | |
| auto | identifier () const noexcept -> std::string_view |
| The reference that caused the error. | |
| auto | location () const noexcept -> const sourcemeta::core::Pointer & |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
Additional Inherited Members | |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
|
inlinenodiscardnoexcept |
Where the problem is, as a pointer from the root of the document that the schema came from
| class sourcemeta::core::SchemaUnknownDialectError |
An error that represents that the dialect of the schema could not determined
Additional Inherited Members | |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
| class sourcemeta::core::SchemaUnknownBaseDialectError |
An error that represents that the base dialect of the schema could not determined
Additional Inherited Members | |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
| class sourcemeta::core::SchemaReferenceObjectResourceError |
In JSON Schema Draft 7 and older, a schema that defines $ref is a reference object where every other keywords are ignored
Public Member Functions | |
|---|---|
| SchemaReferenceObjectResourceError (const std::string_view identifier) | |
| Create a reference object resource error. | |
| auto | identifier () const noexcept -> std::string_view |
| The reference that caused the error. | |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
Additional Inherited Members | |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
| class sourcemeta::core::SchemaDialectImpossibleError |
A schema names the dialect it is written against through a keyword, and the dialect it names may be one that gives that very keyword no meaning. Such a declaration asserts the conditions under which it could not have been written, so no reading of the schema honours it. The caller has to name such a dialect from the outside instead
Public Member Functions | |
|---|---|
| SchemaDialectImpossibleError (const std::string_view keyword, const std::string_view dialect, sourcemeta::core::Pointer schema_location) | |
| Create a dialect impossibility error. | |
| auto | keyword () const noexcept -> std::string_view |
| The keyword that names the dialect. | |
| auto | dialect () const noexcept -> std::string_view |
| The dialect that the schema names. | |
| auto | location () const noexcept -> const sourcemeta::core::Pointer & |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
Additional Inherited Members | |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
|
inlinenodiscardnoexcept |
Where the declaration is, as a pointer from the root of the document that the schema came from
| class sourcemeta::core::SchemaKeywordError |
An error that represents a schema keyword error
Public Member Functions | |
|---|---|
| SchemaKeywordError (const StaticString message, const std::string_view keyword, const std::string_view value) | |
| Create a keyword error. | |
| auto | value () const noexcept -> std::string_view |
| The value that caused the error. | |
| auto | keyword () const noexcept -> std::string_view |
| The keyword that caused the error. | |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
Additional Inherited Members | |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
| class sourcemeta::core::SchemaContainerError |
An error that represents a place bundling was told to put schemas into but cannot
Public Member Functions | |
|---|---|
| SchemaContainerError (const StaticString message, sourcemeta::core::Pointer location) | |
| Create a container error. | |
| auto | location () const noexcept -> const sourcemeta::core::Pointer & |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
Additional Inherited Members | |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
|
inlinenodiscardnoexcept |
Where the container is, as a pointer from the root of the document that was being bundled
| class sourcemeta::core::SchemaFrameError |
An error that represents a schema frame error
Public Member Functions | |
|---|---|
| SchemaFrameError (const StaticString message, const std::string_view identifier) | |
| Create a framing error. | |
| auto | identifier () const noexcept -> std::string_view |
| The identifier of the schema that caused the error. | |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
Additional Inherited Members | |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
| class sourcemeta::core::SchemaFrameLimitError |
An error that represents a schema that needs more frame locations than the caller was willing to spend on analysing it
Public Member Functions | |
|---|---|
| SchemaFrameLimitError (const std::uint64_t limit) noexcept | |
| Create a framing limit error. | |
| auto | limit () const noexcept -> std::uint64_t |
| The maximum number of locations that framing was allowed to register. | |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
Additional Inherited Members | |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
| class sourcemeta::core::SchemaAnchorCollisionError |
An error that represents a schema anchor collision error
Public Member Functions | |
|---|---|
| SchemaAnchorCollisionError (const std::string_view identifier, sourcemeta::core::Pointer location, sourcemeta::core::Pointer other) | |
| Create an anchor collision error. | |
| auto | identifier () const noexcept -> std::string_view |
| The anchor that collided. | |
| auto | location () const noexcept -> const sourcemeta::core::Pointer & |
| auto | other () const noexcept -> const sourcemeta::core::Pointer & |
| The other place that declares the same anchor. | |
| Public Member Functions inherited from sourcemeta::core::Error | |
| auto | message () const noexcept -> StaticString |
Additional Inherited Members | |
| Protected Member Functions inherited from sourcemeta::core::Error | |
| Error (const StaticString message) noexcept | |
| Construct the error given its message. | |
|
inlinenodiscardnoexcept |
Where the problem is, as a pointer from the root of the document that the schema came from
| class sourcemeta::core::SchemaFrame |
This class performs a static analysis pass on the input schema, computing things such as the static identifiers and references of a schema.
For example:
Public Types | |
|---|---|
| enum class | Mode : std::uint8_t { Root , Locations , References , Pointers } |
| enum class | IdentifierMode : std::uint8_t { Additional , Fallback } |
| enum class | LocationType : std::uint8_t { LocationType::Resource , LocationType::Anchor , LocationType::Pointer , LocationType::Subschema } |
| using | Paths = std::vector<sourcemeta::core::WeakPointer> |
| A list of paths to frame within a schema wrapper. | |
Public Member Functions | |
| SchemaFrame (const SchemaFrame &)=delete | |
| SchemaFrame (SchemaFrame &&)=delete | |
| auto | mode () const noexcept -> Mode |
| Query the current mode that the schema frame was configured with. | |
| auto | to_json (const SchemaResolver &resolver, const std::optional< sourcemeta::core::PointerPositionTracker > &tracker=std::nullopt) const -> sourcemeta::core::JSON |
| Export the frame as JSON. | |
| SchemaFrame (const Mode mode, const sourcemeta::core::JSON &root, const SchemaWalker &walker, const SchemaResolver &resolver, std::string_view default_dialect="", std::string_view default_id="", IdentifierMode identifier_mode=IdentifierMode::Additional, const Paths &paths={sourcemeta::core::EMPTY_WEAK_POINTER}, std::string_view default_base="", std::uint64_t max_locations=std::numeric_limits< std::uint64_t >::max()) | |
| auto | location (const SchemaReferenceType type, const std::string_view uri) const -> std::optional< std::reference_wrapper< const Location > > |
| auto | location_count () const noexcept -> std::size_t |
| The number of locations in the frame. | |
| auto | reference_count () const noexcept -> std::size_t |
| The number of references in the frame. | |
| auto | has_dynamic_references () const noexcept -> bool |
| Check whether the analysed schema makes use of dynamic referencing at all. | |
| auto | standalone () const noexcept -> bool |
| Check whether the analysed schema has no external references. | |
| auto | standalone_ignoring_metaschemas () const noexcept -> bool |
| auto | root () const noexcept -> const sourcemeta::core::JSON::String & |
| Get the root schema identifier (empty if none). | |
| auto | root_location () const -> std::optional< std::reference_wrapper< const Location > > |
| auto | metaschema (const SchemaResolver &resolver) const -> const sourcemeta::core::JSON & |
| auto | vocabularies (const Location &location, const SchemaResolver &resolver) const -> const SchemaVocabularies & |
| auto | uri (const Location &location, const sourcemeta::core::WeakPointer &relative_schema_location=sourcemeta::core::EMPTY_WEAK_POINTER) const -> sourcemeta::core::JSON::String |
| Get the URI associated with a location entry. | |
| auto | traverse (const Location &location, const sourcemeta::core::WeakPointer &relative_schema_location) const -> std::optional< std::reference_wrapper< const Location > > |
| Get the location associated by traversing a pointer from another location. | |
| auto | traverse (const std::string_view uri) const -> std::optional< std::reference_wrapper< const Location > > |
| Get the location associated with a given URI. | |
| auto | traverse (const sourcemeta::core::WeakPointer &pointer) const -> std::optional< std::reference_wrapper< const Location > > |
| Get the location associated with a given pointer. | |
| auto | traverse (const sourcemeta::core::WeakPointer &pointer, const LocationType type) const -> std::optional< std::reference_wrapper< const Location > > |
| Get the location of a specific type associated with a given pointer. | |
| auto | uri (const sourcemeta::core::WeakPointer &pointer) const -> std::optional< std::reference_wrapper< const sourcemeta::core::JSON::String > > |
| Turn an absolute pointer into a location URI. | |
| auto | dereference (const Location &location, const sourcemeta::core::WeakPointer &relative_schema_location=sourcemeta::core::EMPTY_WEAK_POINTER) const -> std::pair< SchemaReferenceType, std::optional< std::reference_wrapper< const Location > > > |
| Try to dereference a reference location into its destination location. | |
| template<std::invocable< const Location & > F> | |
| auto | for_each_subschema (const F &callback) const -> void |
| template<std::invocable< const Location & > F> | |
| auto | for_each_subschema_under (const sourcemeta::core::WeakPointer &pointer, const F &callback) const -> void |
| template<std::predicate< const Location & > F> | |
| auto | any_subschema (const F &predicate) const -> bool |
| Check whether any schema resource or subschema satisfies the predicate. | |
| template<std::predicate< const Location & > F> | |
| auto | any_subschema_under (const sourcemeta::core::WeakPointer &pointer, const F &predicate) const -> bool |
| template<std::invocable< std::string_view, const Location & > F> | |
| auto | for_each_anchor (const SchemaReferenceType type, const F &callback) const -> void |
| Iterate over every anchor of the given kind, along with its URI. | |
| template<std::predicate< std::string_view, const Location & > F> | |
| auto | any_anchor (const SchemaReferenceType type, const F &predicate) const -> bool |
| Check whether any anchor of the given kind satisfies the predicate. | |
| template<std::invocable< std::string_view, const Location & > F> | |
| auto | for_each_resource (const F &callback) const -> void |
| Iterate over every schema resource, along with its URI. | |
| template<std::invocable< SchemaReferenceType, std::string_view, const Location & > F> | |
| auto | for_each_location (const F &callback) const -> void |
| Iterate over every location, whatever kind it is. | |
| template<std::predicate< SchemaReferenceType, std::string_view, const Location & > F> | |
| auto | any_location (const F &predicate) const -> bool |
| Check whether any location satisfies the predicate. | |
| template<std::invocable< SchemaReferenceType, const sourcemeta::core::WeakPointer &, const Reference & > F> | |
| auto | for_each_reference (const F &callback) const -> void |
| Iterate over every reference, along with the pointer it originates from. | |
| template<std::predicate< SchemaReferenceType, const sourcemeta::core::WeakPointer &, const Reference & > F> | |
| auto | any_reference (const F &predicate) const -> bool |
| Check whether any reference satisfies the predicate. | |
| template<std::invocable< SchemaReferenceType, const sourcemeta::core::WeakPointer &, const Reference & > F> | |
| auto | for_each_reference_from (const sourcemeta::core::WeakPointer &pointer, const F &callback) const -> void |
| Iterate over every reference that originates at or below the given pointer. | |
| template<std::predicate< SchemaReferenceType, const sourcemeta::core::WeakPointer &, const Reference & > F> | |
| auto | any_reference_from (const sourcemeta::core::WeakPointer &pointer, const F &predicate) const -> bool |
| template<std::invocable< SchemaReferenceType, const sourcemeta::core::WeakPointer &, const Reference & > F> | |
| auto | for_each_reference_into (const sourcemeta::core::WeakPointer &pointer, const F &callback) const -> void |
| template<std::predicate< SchemaReferenceType, const sourcemeta::core::WeakPointer &, const Reference & > F> | |
| auto | any_reference_into (const sourcemeta::core::WeakPointer &pointer, const F &predicate) const -> bool |
| template<std::invocable< std::string_view > F> | |
| auto | for_each_resource_uri (const F &callback) const -> void |
| Iterate over all resource URIs in the frame. | |
| template<std::invocable< const sourcemeta::core::WeakPointer &, const Reference & > F> | |
| auto | for_each_unresolved_reference (const F &callback) const -> void |
| auto | has_references_to (const sourcemeta::core::WeakPointer &pointer) const -> bool |
| Check if there are any references to a given location pointer. | |
| auto | has_references_through (const sourcemeta::core::WeakPointer &pointer) const -> bool |
| Check if there are any references that go through a given location pointer. | |
| auto | has_references_through (const sourcemeta::core::WeakPointer &pointer, const sourcemeta::core::WeakPointer::Token &tail) const -> bool |
| auto | relative_instance_location (const Location &location) const -> sourcemeta::core::WeakPointer |
| Get the relative instance location pointer for a given location entry. | |
| auto | is_reachable (const Location &base, const Location &location, const SchemaWalker &walker, const SchemaResolver &resolver) const -> bool |
| Determines if a location could be evaluated during validation. | |
|
strong |
|
strong |
The mode of framing. More extensive analysis can be compute and memory intensive. Each mode is a superset of the previous one. Note that sourcemeta::core::SchemaFrame::Mode::Root reports on a single schema, so framing a wrapper that holds more than one yields no locations
sourcemeta::core::SchemaFrame::Mode::Locations and sourcemeta::core::SchemaFrame::Mode::References locate the schemas of the document rather than each of its JSON Pointers, and the latter also locates whatever place a reference names. Reach for sourcemeta::core::SchemaFrame::Mode::Pointers only to address a keyword or a value of the document by URI, as computing those locations tends to dominate the cost of framing
| sourcemeta::core::SchemaFrame::SchemaFrame | ( | const Mode | mode, |
| const sourcemeta::core::JSON & | root, | ||
| const SchemaWalker & | walker, | ||
| const SchemaResolver & | resolver, | ||
| std::string_view | default_dialect = "", | ||
| std::string_view | default_id = "", | ||
| IdentifierMode | identifier_mode = IdentifierMode::Additional, | ||
| const Paths & | paths = {sourcemeta::core::EMPTY_WEAK_POINTER}, | ||
| std::string_view | default_base = "", | ||
| std::uint64_t | max_locations = std::numeric_limits< std::uint64_t >::max() ) |
Frame a schema or set of schemas from a given root. Passing multiple paths that have any overlap is undefined behaviour
A frame is analysed once, on construction, and is immutable afterwards
The resulting locations point into the schema rather than copying from it, so the schema must outlive the frame. The same goes for default_dialect, as a location that has no dialect of its own reports the default back as a view into what the caller passed. In contrast, default_id and default_base are copied, so they do not need to outlive this call
Pass default_base to state the base URI that the document was retrieved from, which anything that declares no identifier of its own inherits, and which a relative identifier or reference resolves against. Unlike default_id, this does not claim that the document declares an identifier, so a pointer into it keeps being addressed from the top of the document rather than from wherever a path begins, and a document that declares no identifier still reports none
Framing a schema that declares nested identifiers registers a location per enclosing base, so what an untrusted schema costs to analyse grows faster than the schema itself does. Pass max_locations to bound that, throwing sourcemeta::core::SchemaFrameLimitError rather than analysing past it. What the limit buys depends on the mode, as sourcemeta::core::SchemaFrame::Mode::Pointers locates every JSON Pointer of the document rather than only the schemas of it. Note this bounds what framing registers rather than every last thing it does, as walking the document costs something even where nothing comes of it. Bounding the size of the document remains the caller's to do
|
inlinenodiscard |
Check whether any reference originating at or below the given pointer satisfies the predicate
|
inlinenodiscard |
Check whether any reference whose destination resolves at or below the given pointer satisfies the predicate
|
inlinenodiscard |
Check whether any schema resource or subschema strictly below the given pointer satisfies the predicate
|
inline |
Iterate over every reference whose destination resolves at or below the given pointer. Note that unlike sourcemeta::core::SchemaFrame::has_references_to, which matches a destination exactly, this covers the entire subtree
|
inline |
Iterate over every schema resource and subschema, skipping the pointer and anchor entries that do not stand for a schema of their own
|
inline |
Iterate over every schema resource and subschema strictly below the given pointer
|
inline |
Iterate over all unresolved references (where destination cannot be traversed)
|
nodiscard |
Check if there are any references that go through a given location pointer with a tail token
|
nodiscard |
|
nodiscard |
Get the meta-schema of the analysed schema, preferring one embedded in the document itself over what the resolver knows about
|
nodiscard |
Get the location entry of the schema that was analysed. Unlike sourcemeta::core::SchemaFrame::root, this works for anonymous schemas
|
nodiscardnoexcept |
Check whether the analysed schema has no external references other than to the dialects it declares. Callers that resolve references between schemas but leave dialects as they are want this rather than the stricter question, as a dialect they were never going to resolve should not count against them
|
nodiscard |
Get the vocabularies associated with a location entry. The frame owns the result, computing it at most once per dialect that it came across. Note that as with the meta-schemas that framing found embedded in the document, what the first resolver reported for a given dialect is what every later call reports, whichever resolver they pass
| struct sourcemeta::core::SchemaWalkerResult |
A structure that encapsulates the result of walker over a specific keyword
Public Member Functions | |
|---|---|
| SchemaWalkerResult (const SchemaWalkerResult &)=delete | |
| SchemaWalkerResult (SchemaWalkerResult &&)=default | |
| Move a walker result. | |
| constexpr | SchemaWalkerResult (SchemaKeywordType keyword_type, std::optional< SchemaVocabularies::URIView > keyword_vocabulary, std::span< const std::string_view > keyword_dependencies, std::span< const std::string_view > keyword_order_dependencies, sourcemeta::core::JSON::TypeSet keyword_instances) |
Public Attributes | |
| SchemaKeywordType | type |
| The walker strategy to continue traversing across the schema. | |
| std::optional< SchemaVocabularies::URIView > | vocabulary |
| The vocabulary associated with the keyword, if any. | |
| std::span< const std::string_view > | dependencies |
| std::span< const std::string_view > | order_dependencies |
| sourcemeta::core::JSON::TypeSet | instances |
| The JSON instance types that this keyword applies to (empty means all). | |
|
inlineconstexpr |
Describe a keyword from its type, vocabulary, dependencies, and the instance types it applies to
| std::span<const std::string_view> sourcemeta::core::SchemaWalkerResult::dependencies |
The keywords a given keyword depends on (if any) during the evaluation process
| std::span<const std::string_view> sourcemeta::core::SchemaWalkerResult::order_dependencies |
The keywords a given keyword depends on for evaluation ordering purposes only (not semantic dependencies)
| struct sourcemeta::core::SchemaVocabularies |
Optimized vocabulary set using bitflags for known vocabularies and a fallback std::unordered_map for custom vocabularies.
Public Types | |
|---|---|
| enum class | Known : std::uint8_t { JSON_SCHEMA_DRAFT_0 = 0 , JSON_SCHEMA_DRAFT_0_HYPER = 1 , JSON_SCHEMA_DRAFT_1 = 2 , JSON_SCHEMA_DRAFT_1_HYPER = 3 , JSON_SCHEMA_DRAFT_2 = 4 , JSON_SCHEMA_DRAFT_2_HYPER = 5 , JSON_SCHEMA_DRAFT_3 = 6 , JSON_SCHEMA_DRAFT_3_HYPER = 7 , JSON_SCHEMA_DRAFT_4 = 8 , JSON_SCHEMA_DRAFT_4_HYPER = 9 , JSON_SCHEMA_DRAFT_6 = 10 , JSON_SCHEMA_DRAFT_6_HYPER = 11 , JSON_SCHEMA_DRAFT_7 = 12 , JSON_SCHEMA_DRAFT_7_HYPER = 13 , JSON_SCHEMA_2019_09_CORE = 14 , JSON_SCHEMA_2019_09_APPLICATOR = 15 , JSON_SCHEMA_2019_09_VALIDATION = 16 , JSON_SCHEMA_2019_09_META_DATA = 17 , JSON_SCHEMA_2019_09_FORMAT = 18 , JSON_SCHEMA_2019_09_CONTENT = 19 , JSON_SCHEMA_2019_09_HYPER_SCHEMA = 20 , JSON_SCHEMA_2020_12_CORE = 21 , JSON_SCHEMA_2020_12_APPLICATOR = 22 , JSON_SCHEMA_2020_12_UNEVALUATED = 23 , JSON_SCHEMA_2020_12_VALIDATION = 24 , JSON_SCHEMA_2020_12_META_DATA = 25 , JSON_SCHEMA_2020_12_FORMAT_ANNOTATION = 26 , JSON_SCHEMA_2020_12_FORMAT_ASSERTION = 27 , JSON_SCHEMA_2020_12_CONTENT = 28 , OPENAPI_3_0_BASE = 29 , OPENAPI_3_1_BASE = 30 , OPENAPI_3_2_BASE = 31 , SOURCEMETA_EXTENSION_V1 = 32 } |
| Every vocabulary that this implementation recognises out of the box. More... | |
| using | URI = std::variant<Known, sourcemeta::core::JSON::String> |
| using | URIView = std::variant<Known, std::string_view> |
Public Member Functions | |
| SchemaVocabularies (const SchemaVocabularies &)=default | |
| Copy a vocabulary set. | |
| SchemaVocabularies (SchemaVocabularies &&) noexcept=default | |
| Move a vocabulary set. | |
| SchemaVocabularies (std::initializer_list< std::pair< sourcemeta::core::JSON::String, bool > > init) | |
| Construct from initializer list. | |
| SchemaVocabularies (std::initializer_list< std::pair< Known, bool > > init) | |
| Construct from initializer list using known vocabulary enums. | |
| auto | contains (const sourcemeta::core::JSON::String &uri) const noexcept -> bool |
| Check if a vocabulary is enabled. | |
| auto | contains (Known vocabulary) const noexcept -> bool |
| Check if a known vocabulary is enabled. | |
| auto | contains_any (std::initializer_list< Known > vocabularies) const noexcept -> bool |
| Check if any of the given known vocabularies are enabled. | |
| auto | insert (const sourcemeta::core::JSON::String &uri, bool required) noexcept -> void |
| Insert a vocabulary with its required/optional status. | |
| auto | insert (Known vocabulary, bool required) noexcept -> void |
| Insert a known vocabulary with its required/optional status. | |
| auto | get (const sourcemeta::core::JSON::String &uri) const noexcept -> std::optional< bool > |
| Get vocabulary status by URI. | |
| auto | get (Known vocabulary) const noexcept -> std::optional< bool > |
| Get known vocabulary status. | |
| auto | size () const noexcept -> std::size_t |
| Get the number of vocabularies (required + optional + custom). | |
| auto | empty () const noexcept -> bool |
| Check if there are no vocabularies. | |
| auto | has_unknown () const noexcept -> bool |
| Check if there are any unknown vocabularies. | |
| template<typename Callback> | |
| auto | for_each (const Callback &callback) const -> void |
| Iterate over every vocabulary, along with whether it is required. | |
| auto | throw_if_any_unsupported (const std::unordered_set< URI > &supported, StaticString message) const -> void |
Static Public Attributes | |
| static constexpr std::size_t | KNOWN_VOCABULARY_COUNT = 33 |
| How many vocabularies this implementation recognises out of the box. | |
| using sourcemeta::core::SchemaVocabularies::URI = std::variant<Known, sourcemeta::core::JSON::String> |
| using sourcemeta::core::SchemaVocabularies::URIView = std::variant<Known, std::string_view> |
A vocabulary URI that does not own its custom string, for tables that point at storage that outlives them
|
strong |
Every vocabulary that this implementation recognises out of the box.
| auto sourcemeta::core::SchemaVocabularies::throw_if_any_unsupported | ( | const std::unordered_set< URI > & | supported, |
| StaticString | message ) const -> void |
Throw if the current vocabularies have required ones outside the given supported set
| using sourcemeta::core::SchemaDependencyCallback = std::function<void(const SchemaDependency &)> |
A callback to report every dependency that analysis finds
| using sourcemeta::core::SchemaResolver = std::function<SchemaResolverResult(std::string_view)> |
Some functions need to reference other schemas by their URIs. To accomplish this in a generic and flexible way, these functions take resolver functions as arguments, of the type sourcemeta::core::SchemaResolver.
For convenience, we provide the following default resolvers:
You can implement resolvers to read from a local storage, to send HTTP requests, or anything your application might require. Unless your resolver is trivial, it is recommended to create a callable object that implements the function interface.
What a sourcemeta::core::SchemaResolver hands back: either a schema it owns, or a reference to one that outlives the call
For walking purposes, some functions need to understand which JSON Schema keywords declare other JSON Schema definitions. To accomplish this in a generic and flexible way that does not assume the use any vocabulary other than core, these functions take a walker function as argument.
|
strong |
|
strong |
All the known JSON Schema base dialects
|
strong |
Determines the type of a JSON Schema keyword
| Enumerator | |
|---|---|
| Unknown | The JSON Schema keyword is unknown. |
| Assertion | The JSON Schema keyword is a non-applicator assertion. |
| Annotation | The JSON Schema keyword is a non-applicator annotation. |
| Reference | The JSON Schema keyword is a reference. |
| Other | The JSON Schema keyword is known but doesn't match any other type. |
| Comment | The JSON Schema keyword is considered to be a comment without any additional meaning |
| LocationMembers | The JSON Schema keyword is a reserved location that potentially takes an object as argument, whose values are potentially JSON Schema definitions |
| ApplicatorMembersTraversePropertyStatic | The JSON Schema keyword is an applicator that potentially takes an object as argument, whose values are potentially JSON Schema definitions. The instance traverses based on the members as property names |
| ApplicatorMembersTraversePropertyRegex | The JSON Schema keyword is an applicator that potentially takes an object as argument, whose values are potentially JSON Schema definitions. The instance traverses based on the members as property regular expressions |
| ApplicatorValueTraverseSomeProperty | The JSON Schema keyword is an applicator that potentially takes a JSON Schema definition as an argument The instance traverses to some of the properties |
| ApplicatorValueTraverseAnyPropertyKey | The JSON Schema keyword is an applicator that potentially takes a JSON Schema definition as an argument The instance traverses to any property key |
| ApplicatorValueTraverseAnyItem | The JSON Schema keyword is an applicator that potentially takes a JSON Schema definition as an argument The instance traverses to any item |
| ApplicatorValueTraverseSomeItem | The JSON Schema keyword is an applicator that potentially takes a JSON Schema definition as an argument The instance traverses to some of the items |
| ApplicatorValueTraverseParent | The JSON Schema keyword is an applicator that potentially takes a JSON Schema definition as an argument The instance traverses back to the parent |
| ApplicatorElementsTraverseItem | The JSON Schema keyword is an applicator that potentially takes an array of potentially JSON Schema definitions as an argument The instance traverses based on the element indexes |
| ApplicatorValueOrElementsTraverseAnyItemOrItem | The JSON Schema keyword is an applicator that may take a JSON Schema definition or an array of potentially JSON Schema definitions as an argument The instance traverses to any item or based on the element indexes |
| ApplicatorValueOrElementsInPlace | The JSON Schema keyword is an applicator that may take a JSON Schema definition or an array of potentially JSON Schema definitions as an argument without affecting the instance location. The instance does not traverse |
| ApplicatorMembersInPlaceSome | The JSON Schema keyword is an applicator that potentially takes an object as argument, whose values are potentially JSON Schema definitions without affecting the instance location. The instance does not traverse |
| ApplicatorElementsInPlace | The JSON Schema keyword is an applicator that potentially takes an array of potentially JSON Schema definitions as an argument without affecting the instance location. The instance does not traverse |
| ApplicatorElementsInPlaceSome | The JSON Schema keyword is an applicator that potentially takes an array of potentially JSON Schema definitions as an argument without affecting the instance location The instance does not traverse, and only some of the elements apply. |
| ApplicatorElementsInPlaceSomeNegate | The JSON Schema keyword is an applicator that potentially takes an array of potentially JSON Schema definitions as an argument without affecting the instance location The instance does not traverse, and only some of the elements apply in negated form. |
| ApplicatorValueInPlaceMaybe | The JSON Schema keyword is an applicator that potentially takes a JSON Schema definition as an argument without affecting the instance location. The instance does not traverse, and only applies some of the times. |
| ApplicatorValueInPlaceOther | The JSON Schema keyword is an applicator that potentially takes a JSON Schema definition as an argument but its evaluation follows special rules. The instance does not traverse |
| ApplicatorValueInPlaceNegate | The JSON Schema keyword is an applicator that potentially takes a JSON Schema definition as an argument but the instance is expected to not validate against it. The instance does not traverse |
|
strong |
| SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto sourcemeta::core::schema_bundle | ( | const sourcemeta::core::JSON & | schema, |
| const SchemaWalker & | walker, | ||
| const SchemaResolver & | resolver, | ||
| std::string_view | default_dialect = "", | ||
| std::string_view | default_id = "", | ||
| const SchemaBundleOptions & | options = {} ) -> sourcemeta::core::JSON |
This function bundles a JSON Schema (starting from Draft 4) by embedding every remote reference into the top level schema resource, handling circular dependencies and more. This overload returns a new schema, without mutating the input schema. For example:
| SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto sourcemeta::core::schema_bundle | ( | sourcemeta::core::JSON & | schema, |
| const SchemaWalker & | walker, | ||
| const SchemaResolver & | resolver, | ||
| std::string_view | default_dialect = "", | ||
| std::string_view | default_id = "", | ||
| const SchemaBundleOptions & | options = {} ) -> std::uint64_t |
This function bundles a JSON Schema (starting from Draft 4) by embedding every remote reference into the top level schema resource, handling circular dependencies and more. This overload mutates the input schema. For example:
Returns how many frame locations the analysis registered, which a caller that spends from the same allowance elsewhere takes off its own count.
| SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto sourcemeta::core::schema_dependencies | ( | const sourcemeta::core::JSON & | schema, |
| const SchemaWalker & | walker, | ||
| const SchemaResolver & | resolver, | ||
| const SchemaDependencyCallback & | callback, | ||
| const SchemaDependenciesOptions & | options = {} ) -> std::uint64_t |
This function reports every reference that a JSON Schema makes to another document, transitively, so a document that several references name is reported once for each of them and a caller wanting one edge per document takes it from there. Only the reference that had analysis resolve a document carries it, which leaves a reference naming what another document carries within itself, one reaching a document already read, and one naming what the caller says it holds, reported with nothing to fetch. A reference that nothing answers for when it is read leads somewhere only once a document that arrived later settles it, so that one is reported after the references of every document read in between, and one that nothing ever answers for is no dependency at all, which the options above hand over separately. Official schemas are reported when a reference names them and left out when a dialect declaration does, and neither is traversed into. For example:
Returns how many frame locations the analysis registered, which a caller that spends from the same allowance elsewhere takes off its own count.
Analysis throws where it cannot go on. A dialect that nothing can produce ends it, as does a document that cannot be read as a schema at all, and so does a reference that nothing answers for, though only once every document reached has been read, since one of them may still carry what an earlier reference asked for. A reference that lands nowhere within a document the walk went on to read is reported all the same, while one that lands nowhere within the document making it ends analysis. Where the paths above confine analysis to part of a document, what the rest of that document holds is none of its business, so a reference into the part left out is neither followed, reported, nor complained about.
| SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto sourcemeta::core::schema_format | ( | sourcemeta::core::JSON & | schema, |
| const SchemaFrame & | frame ) -> void |
This function reorders the properties of every subschema that the given frame reports, following an opinionated JSON Schema aware order, modifying the schema in place. Note that doing so invalidates the given frame, as the locations it holds point into the schema. For example:
| SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto sourcemeta::core::schema_identifier_keyword | ( | const SchemaBaseDialect | base_dialect | ) | -> std::string_view |
The keyword that carries a schema identifier in the given base dialect. For example:
|
noexcept |
Check if a given identifier corresponds to a known built-in schema
|
noexcept |
| SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto sourcemeta::core::schema_reidentify | ( | sourcemeta::core::JSON & | schema, |
| std::string_view | new_identifier, | ||
| const SchemaBaseDialect | base_dialect ) -> void |
A shortcut to sourcemeta::core::schema_reidentify if you know the base dialect of the schema. A base dialect names the keyword that declares an identifier without saying whether the dialect in force gives that keyword any meaning, so this overload cannot make that check and the caller has to make it instead. For example:
| SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto sourcemeta::core::schema_reidentify | ( | sourcemeta::core::JSON & | schema, |
| std::string_view | new_identifier, | ||
| const SchemaWalker & | walker, | ||
| const SchemaResolver & | resolver, | ||
| std::string_view | default_dialect = "" ) -> void |
This function sets the identifier of a schema, replacing the existing one, if any. For example:
| SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto sourcemeta::core::schema_resolver | ( | const std::string_view | identifier | ) | -> SchemaResolverResult |
A default resolver that relies on built-in official schemas. The schemas are parsed once and handed back by reference, so they must not outlive the program.
| SOURCEMETA_CORE_JSONSCHEMA_EXPORT auto sourcemeta::core::schema_walker | ( | const std::string_view | keyword, |
| const SchemaVocabularies & | vocabularies ) -> const SchemaWalkerResult & |
A default schema walker with support for a wide range of drafts