42fa9e4965
this PR makes the following changes to update the underlying license model to have more expressive capabilities it also provides some guarantee's surrounding the license values themselves - Licenses are updated from string -> pkg.LicenseSet which contain pkg.License with the following fields: - original `Value` read by syft - If it's possible to construct licenses will always have a valid SPDX expression for downstream consumption - the above is run against a generated list of SPDX license ID to try and find the correct ID - SPDX concluded vs declared is added to the new struct - URL source for license is added to the new struct - Location source is added to the new struct to show where the expression was pulled from |
||
---|---|---|
.. | ||
generate.go | ||
README.md | ||
schema-1.0.0.json | ||
schema-1.0.1.json | ||
schema-1.0.2.json | ||
schema-1.0.3.json | ||
schema-1.0.4.json | ||
schema-1.0.5.json | ||
schema-1.1.0.json | ||
schema-2.0.0.json | ||
schema-2.0.1.json | ||
schema-2.0.2.json | ||
schema-3.0.0.json | ||
schema-3.0.1.json | ||
schema-3.1.0.json | ||
schema-3.1.1.json | ||
schema-3.2.1.json | ||
schema-3.2.2.json | ||
schema-3.2.3.json | ||
schema-3.2.4.json | ||
schema-3.3.0.json | ||
schema-3.3.1.json | ||
schema-3.3.2.json | ||
schema-4.0.0.json | ||
schema-4.1.0.json | ||
schema-5.0.0.json | ||
schema-5.0.1.json | ||
schema-5.1.0.json | ||
schema-6.0.0.json | ||
schema-6.1.0.json | ||
schema-6.2.0.json | ||
schema-7.0.0.json | ||
schema-7.0.1.json | ||
schema-7.1.0.json | ||
schema-7.1.1.json | ||
schema-7.1.2.json | ||
schema-7.1.3.json | ||
schema-7.1.4.json | ||
schema-7.1.5.json | ||
schema-7.1.6.json | ||
schema-8.0.0.json | ||
vnd.syft+json |
JSON Schema
This is the JSON schema for output from the JSON presenters (syft packages <img> -o json
and syft power-user <img>
). The required inputs for defining the JSON schema are as follows:
- the value of
internal.JSONSchemaVersion
that governs the schema filename - the
Document
struct definition withininternal/presenters/poweruser/json_document.go
that governs the overall document shape - the
artifactMetadataContainer
struct definition withinschema/json/generate.go
that governs the allowable shapes ofpkg.Package.Metadata
With regard to testing the JSON schema, integration test cases provided by the developer are used as examples to validate that JSON output from Syft is always valid relative to the schema/json/schema-$VERSION.json
file.
Versioning
Versioning the JSON schema must be done manually by changing the JSONSchemaVersion
constant within internal/constants.go
.
This schema is being versioned based off of the "SchemaVer" guidelines, which slightly diverges from Semantic Versioning to tailor for the purposes of data models.
Given a version number format MODEL.REVISION.ADDITION
:
MODEL
: increment when you make a breaking schema change which will prevent interaction with any historical dataREVISION
: increment when you make a schema change which may prevent interaction with some historical dataADDITION
: increment when you make a schema change that is compatible with all historical data
Adding a New pkg.*Metadata
Type
When adding a new pkg.*Metadata
that is assigned to the pkg.Package.Metadata
struct field it is important that a few things
are done:
- a new integration test case is added to
test/integration/catalog_packages_cases_test.go
that exercises the new package type with the new metadata - the new metadata struct is added to the
artifactMetadataContainer
struct withinschema/json/generate.go
Generating a New Schema
Create the new schema by running cd schema/json && go run generate.go
(note you must be in the schema/json
dir while running this):
- If there is not an existing schema for the given version, then the new schema file will be written to
schema/json/schema-$VERSION.json
- If there is an existing schema for the given version and the new schema matches the existing schema, no action is taken
- If there is an existing schema for the given version and the new schema does not match the existing schema, an error is shown indicating to increment the version appropriately (see the "Versioning" section)
Note: never delete a JSON schema and never change an existing JSON schema once it has been published in a release! Only add new schemas with a newly incremented version. All previous schema files must be stored in the schema/json/
directory.