github.com/nextlinux/gosbom@v0.81.1-0.20230627115839-1ff50c281391/schema/json/README.md (about)

     1  # JSON Schema
     2  
     3  This is the JSON schema for output from the JSON presenters (`gosbom packages <img> -o json` and `gosbom power-user <img>`). The required inputs for defining the JSON schema are as follows:
     4  
     5  - the value of `internal.JSONSchemaVersion` that governs the schema filename
     6  - the `Document` struct definition within `internal/presenters/poweruser/json_document.go` that governs the overall document shape
     7  - the `artifactMetadataContainer` struct definition within `schema/json/generate.go` that governs the allowable shapes of `pkg.Package.Metadata`
     8  
     9  With regard to testing the JSON schema, integration test cases provided by the developer are used as examples to validate that JSON output from Gosbom is always valid relative to the `schema/json/schema-$VERSION.json` file.
    10  
    11  ## Versioning
    12  
    13  Versioning the JSON schema must be done manually by changing the `JSONSchemaVersion` constant within `internal/constants.go`.
    14  
    15  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. 
    16  
    17  Given a version number format `MODEL.REVISION.ADDITION`:
    18  
    19  - `MODEL`: increment when you make a breaking schema change which will prevent interaction with any historical data
    20  - `REVISION`: increment when you make a schema change which may prevent interaction with some historical data
    21  - `ADDITION`: increment when you make a schema change that is compatible with all historical data
    22  
    23  ## Adding a New `pkg.*Metadata` Type
    24  
    25  When adding a new `pkg.*Metadata` that is assigned to the `pkg.Package.Metadata` struct field it is important that a few things
    26  are done:
    27  
    28  - 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
    29  - the new metadata struct is added to the `artifactMetadataContainer` struct within `schema/json/generate.go`
    30  
    31  ## Generating a New Schema
    32  
    33  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):
    34  
    35  - 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`
    36  - If there is an existing schema for the given version and the new schema matches the existing schema, no action is taken
    37  - 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)
    38  
    39  ***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.