AION v2 spec with cognition category validation

packages/veritone-json-schemas/Makefile

@@ -0,0 +1,16 @@
+help: ## Print the list of makefile targets
+	@grep -hE '^[a-zA-Z0-9_\. -]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-45s\033[0m %s\n", $$1, $$2}'
+
+test: ## Test all valid and invalid examples against their respective schemas
+	./scripts/test-examples.sh v2 \
+	&& ./scripts/test-examples.sh v1
+
+# Note: this is old code that I haven't been able to get to run on my laptop, that may be
+# because it no longer works or because I don't have the right yarn/nvm/node/whatever
+# configuration. -kmurray June '25
+build: ## Builds the validator in the dist/ directory
+	yarn
+	yarn test
+	yarn build
+	mkdir -p dist/schemas/vtn-standard
+	cp schemas/*/*.json dist/schemas/vtn-standard

packages/veritone-json-schemas/README.md

@@ -4,16 +4,76 @@ This repo contains all the static JSON schemas used by Veritone.
 This does **not** include the [user-defined schemas registered through Veritone Developer](https://docs.veritone.com/#/developer/data/),
 just the ones that are core to our platform.
 
-## Releasing
+## Adding a new validation contract to AION
+
+Validation contracts are enforced by the JSON schema definitions. In order to add a new
+validation contract you need to understand how JSON Draft-07 schemas handle `allOf` and
+`if-then-else` specifications. See
+https://json-schema.org/draft-07/draft-handrews-json-schema-validation-01
+
+Determine the type of contract: capability or object
+
+### Capability contract
+
+Capability contracts validate against the entire document as a whole. They can enforce that a
+document contains specific fields or fields with specific values.
+
+Capability contracts are triggered when the optional `validationContracts` array is present and
+has one or more values. Each value requires the document to fulfill its validation contract, so
+a document must fulfill _all_ the contracts to be valid. Note that some contracts are compatible
+with each other (i.e. "transcription" with "sentiment") but some contracts are fundamentally
+incompatible because they have conflicting requirements (i.e. "anomaly" and "text"). Where
+possible, contracts should be written so that they are compatible with other contracts.
+
+1. Add the new contract name to the `validationContracts` enum in `masters.json`
+
+1. Define the contract in the top section of `contracts.json`
+   1. Name must be `capability` + the enum you added in the previous step
+   1. Insert the contract alphabetically in the `definitions` object
+   1. Must have an `if` clause that ensures your contract only applies if the enum is present in
+      the `validationContracts` list
+
+1. Add the contract to the list of contract references toward the bottom of the `aion.json`
+   schema file.
+
+
+### Object contract
+
+Object contracts enforce that objects of a certain `type` are valid objects of that type. Object
+contracts apply independently to every object of the specific `type` and cannot enforce anything
+outside that object. This includes objects in the `object` array as well as any object in a
+`series` item.
+
+Object contracts are preferred over capability contracts because they have a local scope that
+affects individual objects and may be mixed in the same object or series array.
+
+1. Add the new object type to the `objectResultTypes` enum in `masters.json`
+   1. Use camelCase for new enum types
+
+1. Define the new contract in the middle section of `contracts.json`
+   1. Name must be `object` + the enum you added to the `objectResultTypes` property
+   1. Insert the contract alphabetically in the `definitions` object
+   1. Must have an `if` clause that ensures your contract only applies if the `type` of the
+      object is appropriate
+
+1. Add the contract to the list of contract references at the end of the `objectResult`
+   definition in `masters.json`
+
+Define your new object contract in the `contracts.json` file (middle section) and prefix it with
+`object`. After defining the contract, make it a requirement of all objects by adding it to the
+list of referenced contracts at the bottom of the `objectResult` definition in the `master.json`
+schema file.
+
+## Publishing
 
 The JSON schema is deployed to the get.aiware.com
 site (https://get.aiware.com/schemas/index.html). 
 This may be deployed manually with
 ```bash
 AWS_PROFILE=default
 aws --profile=$AWS_PROFILE s3 cp schemas/vtn-standard/index.html s3://aiware-prod-public/schemas/index.html
-for schema in $(find schemas/vtn-standard -name '*.json' | grep -v "examples"); do
-  aws --profile=$AWS_PROFILE s3 cp $schema s3://aiware-prod-public/${schema/vtn-standard\//}
+for schema in $(find schemas -name '*.json' | grep -v "examples"); do
+  aws --profile=$AWS_PROFILE s3 cp --dryrun $schema s3://aiware-prod-public/$schema}
 done
 ```
 (with appropriate updates for the local directory)
@@ -60,6 +120,82 @@ So what is the AION validator for then? It has two purposes:
    For instance, at the time of writing, there is no specific validation contract for validating "location detection", 
    but you can use the AION validator to ensure that your GPS data conforms to the expected format.
 
+
+## Local Testing
+
+### Creating tests
+
+Create a test in the `examples` or `invalid-examples` directory. Everything in the `examples`
+directory must be a valid JSON instance of the schema it is associated with. Everything in the
+`invalid-examples` directory must be a JSON instnace that fails validation with the associated
+schema. 
+
+The typical naming convention is `<category-in-kabob-case>_<description-in-kabob-case>`. Specific
+examples that test contract validation should start with `cc` for Capability Contracts and `oc`
+for Object Contracts
+
+### Running tests
+
+We use a containerized tool for validation of the schema and examples. All examples can be
+tested easily with `make test`, however sometimes it is easier to focus on a subset of examples,
+so the following can also be used:
+
+### Test a schema
+
+To run a suite of tests for one schema, run `./test-examples.sh <schema-name>`
+
+In this mode, the test script will verify the schema itself is valid. It will then assert that
+all JSON files in the `examples` directory validate against the schema correctly. It will then
+assert that all JSON files in the `invalid-examples` directory DO NOT validate against the schema.
+
+```
+$ ./test-examples.sh language
+ok     master.json
+ok     language/language.json
+ok     language/examples/basic.json
+ok     language/invalid-examples/empty.json
+ok     language/invalid-examples/missing-language.json
+ok     language/invalid-examples/missing-validation-contract.json```
+```
+
+### Test a specific file
+
+To run a single test for one JSON file, run `./test-examples.sh <file-path>`
+
+In this mode, the only the one file will be validated.
+
+```
+$ ./test-examples.sh language/examples/basic.json
+ok     language/examples/basic.json
+PASS   1 tests passed
+```
+
+### Validate directly with the container sourcemeta/jsonschema
+
+Validate one or more schemas against the jsonschema metadata schema validators with the
+`metaschema` keyword:
+
+```
+docker run --interactive --rm --volume "$PWD:/workspace" \
+  ghcr.io/sourcemeta/jsonschema \
+  metaschema --verbose \
+  schemas/master.json schemas/aion/aion.json
+```
+
+Validate one or more instances against a schema with the `validate` keyword by passing in the
+schema as the first parameter and the instance file as the 2nd. Note that you must also
+include the `$ref`d files as resources (`-r` parameters). The following validates the
+`examples/basic.json` instance file against the `language.json` schema
+
+```
+docker run --interactive --rm --volume "$PWD:/workspace" \
+  ghcr.io/sourcemeta/jsonschema \
+  validate --verbose \
+  -r schemas/master.json \
+  schemas/language/language.json \
+  schemas/language/examples/basic.json
+```
+
 ## Contributing
 
 > See the [veritone-sdk README](../../README.md) for full information.
@@ -69,6 +205,12 @@ So what is the AION validator for then? It has two purposes:
 1. `yarn install` to install dependencies.
 2. run `yarn test` to run the schema validator against all the examples.
 
+### To add a new object type
+
+1. Add new enum to the `objectResultsType` field
+2. Add new structure for the object type
+3. Add new Object Contract to the contracts.json file
+
 ## License
 
 Copyright 2019-2021, Veritone Inc.

packages/veritone-json-schemas/schemas/index.md

@@ -0,0 +1,19 @@
+# Veritone JSON Schemas
+
+## Latest and Major Versions
+
+- [latest](./latest/index.html) is an alias to the latest schema.
+- [v2](./v2/index.html) is an alias to the latest v2.x schema.
+- [v1](./v1/index.html) is an alias to the latest v1.x schemas.
+
+## All Supported Versions
+
+- [v2.0](./v2.0/index.html)
+- [v1.1](./v1.1/index.html)
+- [v1.0](./v1.0/index.html)
+
+``` {=html}
+<style>
+body { max-width: 72em !important; }
+</style>
+```

packages/veritone-json-schemas/schemas/v1/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Version history for version 1 schemas
+
+## Version 1.1 - July 9, 2024
+
+All schemas
+- Added `internalTaskId` for documents
+- Added `tags` to objects
+- Added `fingerprintVector` to objects
+- Added `referenceId` to objects
+- Added `referenceId` to series
+
+AION schema (aion/aion.json)
+- Add embedded fingerprint vectors with `referenceId`
+
+## Version 1.0 - March 6, 2019
+
+Version 1.0 of the Veritone schemas is "pre-history" as versioning support wasn't added until 2025.
+

packages/veritone-json-schemas/schemas/v1/index.md

@@ -0,0 +1,41 @@
+# Veritone Standard JSON Schemas
+
+This directory contains the standard JSON schemas used by Veritone.
+
+## AI Object Notation (AION) Schema
+
+AION (pronounced "eye-on") is a universal schema defintion that describes all Veritone object
+notation instance structures. AION contains no validation requirements.
+
+- [AI Object Notation (AION)](./aion/aion.json)
+
+## Capability Schemas
+
+Capability schemas are subsets of the AION schema that includes validation requirements. Each of
+these schemas must contain a `validationContracts` array that lists the engine capability that
+the AION instance document fulfills.
+
+Some capabilities are compatible with each other (like `transcript`, `language`), but others are
+not (like `text` and `anomaly`)
+
+- [Anomaly](./anomaly/anomaly.json)
+- [Concept](./concept/concept.json)
+- [Entity](./entity/entity.json)
+- [Keyword](./keyword/keyword.json)
+- [Language](./language/language.json)
+- [Object](./object/object.json)
+- [Sentiment](./sentiment/sentiment.json)
+- [Summary](./summary/summary.json)
+- [Text](./text/text.json)
+- [Transcript](./transcript/transcript.json)
+- [Translated Media](./media-translated/media-translated.json)
+
+## Definitions
+
+Definitions referenced by other schemas
+
+- [Master Definitions](./master.json)
+
+## Version History
+
+[CHANGELOG](./CHANGELOG.html)

packages/veritone-json-schemas/schemas/v1/text/invalid-examples/missing-text-contract.json

@@ -0,0 +1,20 @@
+{
+  "schemaId": "https://get.aiware.com/schemas/master.json",
+  "validationContracts": [ "object" ],
+  "object": [
+    {
+      "type": "text",
+      "text": "Le rapide renard brun sauta par dessus le chien paresseux.",
+      "page": 1,
+      "paragraph": 1,
+      "sentence": 1
+    },
+    {
+      "type": "text",
+      "text": "Cela a effrayé le chien.",
+      "page": 1,
+      "paragraph": 1,
+      "sentence": 2
+    }
+  ]
+}

packages/veritone-json-schemas/schemas/v1/transcript/examples/empty-series.json

@@ -0,0 +1,5 @@
+{
+  "schemaId": "https://get.aiware.com/schemas/transcript.json",
+  "validationContracts": ["transcript"],
+  "series": [ ]
+}

packages/veritone-json-schemas/schemas/v1/transcript/invalid-examples/basic.no.series.json

@@ -0,0 +1,4 @@
+{
+  "schemaId": "https://get.aiware.com/schemas/transcript.json",
+  "validationContracts": ["transcript"]
+}

packages/veritone-json-schemas/schemas/v2/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Version history for version 2 schemas
+
+## Version 2.0 - July 3, 2025
+
+- **Versioning introduced.** The reason for introducing versioning is to be more deliberate and
+  concise about what is supported. As new cognitive and generative capabilities are added to the
+  aiWARE ecosystem, it is becoming more critical to update the AION specification in a
+  controlled manner to adjust best practices while still maintaining backward compatibility.
+  - Prior versions are "version 1" and available at [https://get.aiware.com/schemas/v1/index.html](https://get.aiware.com/schemas/v1/index.html)
+  - Uses [symantic versioning](https://semver.org/) conventions: major versions are not backward
+    compatible, but minor versions are.
+  - Individual versions are now immutable, and version number will be incremented for every
+    change.
+  - The official schema for each version is now at
+    `https://get.aiware.com/schemas/vM.N/...` where the version is like `v1.0`, `v1.1`, `v2.0`,
+    `v2.1`, etc. Example: [https://get.aiware.com/schemas/v2.0/index.html](https://get.aiware.com/schemas/v2.0/index.html)
+    - The latest minor version for every major version is also linked under the major
+      version number `vM`. For example, at the time of writing, `v2` is a link to `v2.0`, and will
+      be moved to link to `v2.1` when that version is released. Example:
+      [https://get.aiware.com/schemas/v2/index.html](https://get.aiware.com/schemas/v2/index.html)
+    - The overall latest version will always be version number "latest". Example:
+      [https://get.aiware.com/schemas/latest/index.html](https://get.aiware.com/schemas/latest/index.html)
+    - A full index of all released versions is available at
+      [https://get.aiware.com/schemas/index.html](https://get.aiware.com/schemas/index.html)
+- **Renamed the schema** from "`aion/aion.json`" to "`aion/schema.json`" to match best practice
+  for schema names.
+- **Changed the Content-Type** of all schemas from `application/json` to
+  `application/schema+json` per best practices.
+- **Capability validation** is now performed in the AION schema. Capability validation is the
+  validation contract for the AION document as a whole. Any AION document that contains a list
+  of contracts in the `validationContracts` array is required to validate against the contracts
+  that are listed
+  - The separate "Capability Schema" documents have been deprecated. Now that AION contains all
+    capability validation, there is no longer a need for a separate schema for each
+    capability. If you still need separate schemas for capability validation, please use 
+    [version 1](http://get.aiware.com/schemas/v1/index.html) of the schemas.
+- **Object validation** has been added to AION. Object validation is the validation contract of
+  each individual `object` in AION. Based on the `type` of `object`, that object may
+  need to validate against a contract for the object type. For example, if you specify an object
+  is of `"type": "entity"`, you *MUST* include a `label` and `objectCategory` for that object, you
+  *MAY* provide other fields like `page` or `text`, and you *MUST NOT* provide irrelevant fields like
+  `lipMovement`, `age`, or `mode`.
+  - All legacy object types have object validation requirements. These requirements were
+    designed to accommodate as much of the legacy usage as possible. If your engine does not
+    meet these requirement, we recommend you update your engine. If this is not possible, then
+    continue to use the v1 schemas.
+- **New object types** have been added:
+  - **`licensePlate`** requries a `licensePlate` with a `number`.
+  - **`motorVehicle`** requries a `motorVehicle` that may optionally have a `licensePlate`.
+  - **`ocr`** requires a `text` and `boundingPoly`. The type `"ocr"` is a
+    specialization of the `"text"` type, so an `ocr` object counts as a `text` object for the
+    purposes of validating `"validationContracts": ["text"]`.
+- **Partial word transcription** support has been added. Transcribed `words` now have an optional
+  `partial` property that can be set to `true` when doing real-time trasncription to indicate 
+  that the word or phrase has only been partially transcribed, and may be changed as more context 
+  becomes available.
+
+``` {=html}
+<style>
+body { max-width: 72em !important; }
+</style>
+```