JSON Schema Reference

The AiHint Global Hint has a formal JSON Schema that can be used for automated validation. Any tool that supports JSON Schema Draft-07 can validate an aihint.json file against this schema.

Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": [
    "version",
    "type",
    "target",
    "issuer",
    "score",
    "method",
    "issued_at",
    "expires_at",
    "signature",
    "public_key_url"
  ],
  "properties": {
    "version": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "enum": ["global"]
    },
    "target": {
      "type": "string",
      "format": "uri"
    },
    "issuer": {
      "type": "string",
      "format": "uri"
    },
    "score": {
      "type": "number",
      "minimum": 0.0,
      "maximum": 1.0
    },
    "method": {
      "type": "string"
    },
    "issued_at": {
      "type": "string",
      "format": "date-time"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "comment": {
      "type": ["string", "null"]
    },
    "signature": {
      "type": "string"
    },
    "public_key_url": {
      "type": "string",
      "format": "uri"
    }
  }
}

The canonical copy of this schema is maintained in the repository at schema/aihint-global.schema.json.

Required Fields

All fields are required except comment, which may be null or omitted:

Field	Type Constraint
`version`	Any string (currently `"0.1"`)
`type`	Must be `"global"`
`target`	Valid URI
`issuer`	Valid URI
`score`	Number between 0.0 and 1.0
`method`	Any string
`issued_at`	ISO 8601 date-time
`expires_at`	ISO 8601 date-time
`signature`	Any string (Base64-encoded)
`public_key_url`	Valid URI

Validating with Common Tools

Using `ajv` (Node.js)

npm install ajv ajv-formats

import Ajv from 'ajv';
import addFormats from 'ajv-formats';

const ajv = new Ajv();
addFormats(ajv);

const schema = { /* schema from above */ };
const validate = ajv.compile(schema);

const hint = JSON.parse(fs.readFileSync('aihint.json', 'utf8'));
const valid = validate(hint);

if (!valid) {
  console.error(validate.errors);
}

Using `jsonschema` (Python)

pip install jsonschema

import json
from jsonschema import validate, ValidationError

with open("aihint-global.schema.json") as f:
    schema = json.load(f)

with open("aihint.json") as f:
    hint = json.load(f)

try:
    validate(instance=hint, schema=schema)
    print("Valid AiHint document")
except ValidationError as e:
    print(f"Invalid: {e.message}")

Using `jq` + `check-jsonschema` (CLI)

pip install check-jsonschema
check-jsonschema --schemafile aihint-global.schema.json aihint.json

Valid Document Example

{
  "version": "0.1",
  "type": "global",
  "target": "https://example.com",
  "issuer": "https://trust.aihint.org",
  "score": 0.85,
  "method": "aihint-core-v1",
  "issued_at": "2025-06-15T12:00:00Z",
  "expires_at": "2026-06-15T12:00:00Z",
  "comment": null,
  "signature": "dGhpcyBpcyBhIHNhbXBsZSBzaWduYXR1cmU=",
  "public_key_url": "https://trust.aihint.org/pubkey.pem"
}

Next Steps

Protocol Specification — Full field descriptions and semantics
Signature Algorithm — How signatures are created and verified

Schema​

Required Fields​

Validating with Common Tools​

Using ajv (Node.js)​

Using jsonschema (Python)​

Using jq + check-jsonschema (CLI)​

Valid Document Example​

Next Steps​