model-metadata.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/InterwebAlchemy/model-metadata-central/model-metadata.schema.json",
  "title": "Language Model Metadata",
  "description": "A language model metadata defintion for developer tools",
  "type": "object",
  "properties": {
    "model_id": {
      "description": "The identifier of the model (example: gpt-3.5-turbo)",
      "type": "string"
    },
    "model_name": {
      "description": "The human-friendly name of the model (example: GPT-3.5 Turbo)",
      "type": "string"
    },
    "model_provider": {
      "description": "The provider of the model in lowercase (example: openai)",
      "type": "string"
    },
    "model_description": {
      "description": "A human-friendly description of the model",
      "type": "string"
    },
    "model_info": {
      "description": "Link to a page with more information about the model",
      "type": "string",
      "format": "uri"
    },
    "model_version": {
      "description": "The version of the model (example: 0613)",
      "type": "string"
    },
    "model_type": {
      "description": "The type of model (example: chat)",
      "type": "string",
      "enum": ["chat", "completion", "embedding"]
    },
    "context_window": {
      "description": "The maximum number of tokens in the model's context window",
      "type": "integer",
      "minimum": 1
    },
    "max_tokens": {
      "description": "The maximum number of tokens the model will use to generate a response",
      "type": "integer",
      "minimum": 1
    },
    "cost_per_million_tokens": {
      "description": "The model provider's default token pricing in USD per 1,000,000 tokens. Provider-specific entries may override this on individual providers.",
      "$ref": "#/$defs/token_costs"
    },
    "knowledge_cutoff": {
      "description": "The training data cutoff date for the model",
      "type": "string",
      "format": "date"
    },
    "tokenizer": {
      "description": "Tokenizer family and specific encoding/version used by the model",
      "$ref": "#/$defs/tokenizer_config"
    },
    "tuning": {
      "description": "Tags for things the model was tuned for (example: function, instruction)",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "function",
          "instruction",
          "code",
          "multilingual",
          "multimodal",
          "structured",
          "reasoning"
        ]
      },
      "uniqueItems": true,
      "minItems": 1
    },
    "input_type": {
      "description": "The type of input the model accepts",
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["text", "image", "audio", "video", "other"]
      },
      "default": ["text"],
      "uniqueItems": true,
      "minItems": 1
    },
    "output_type": {
      "description": "The type of output the model generates",
      "type": "array",
      "items": {
        "type": "string",
        "enum": ["text", "image", "audio", "video", "other"]
      },
      "default": ["text"],
      "uniqueItems": true,
      "minItems": 1
    },
    "deprecated": {
      "description": "Whether the model has been deprecated by the provider",
      "type": "boolean",
      "default": false
    },
    "meta_model": {
      "description": "Whether this entry describes a meta-model (e.g. a router) whose effective context window, pricing, tokenizer, and knowledge cutoff are inherited from whichever underlying model handles a given request. Consumers should treat the declared values as best-effort upper bounds, not guarantees.",
      "type": "boolean",
      "default": false
    },
    "providers": {
      "description": "The providers that serve this model and their configuration",
      "type": "array",
      "items": {
        "$ref": "#/$defs/provider_reference"
      },
      "uniqueItems": true,
      "minItems": 1
    }
  },
  "required": ["model_id", "model_type", "context_window"],
  "$defs": {
    "provider_reference": {
      "type": "object",
      "description": "A reference to a provider definition",
      "properties": {
        "provider_id": {
          "description": "The identifier matching a provider in providers/",
          "type": "string"
        },
        "model_id_on_provider": {
          "description": "The model ID as used by this specific provider (may differ from model_id)",
          "type": "string"
        },
        "model_info": {
          "description": "Provider-specific link to this model, such as an aggregator listing or provider docs page",
          "type": "string",
          "format": "uri"
        },
        "cost_per_million_tokens": {
          "description": "Provider-specific token pricing in USD per 1,000,000 tokens. Use this when an aggregator or route prices the model differently from the primary provider.",
          "$ref": "#/$defs/token_costs"
        }
      },
      "required": ["provider_id"]
    },
    "token_costs": {
      "type": "object",
      "description": "Token pricing in USD per 1,000,000 tokens. Each direction may be a single number or a map of modality-specific prices.",
      "properties": {
        "input": {
          "description": "Input token cost. May be a single blended price or modality-specific prices.",
          "$ref": "#/$defs/token_cost_value"
        },
        "cached_input": {
          "description": "Cached input token read cost, when the provider exposes separate cache pricing.",
          "$ref": "#/$defs/token_cost_value"
        },
        "cache_write_input": {
          "description": "Cache write input token cost, when the provider exposes separate cache pricing.",
          "$ref": "#/$defs/token_cost_value"
        },
        "output": {
          "description": "Output token cost. May be a single blended price or modality-specific prices.",
          "$ref": "#/$defs/token_cost_value"
        }
      },
      "additionalProperties": false
    },
    "token_cost_value": {
      "description": "A token price in USD per 1,000,000 tokens, either as one number or split by modality.",
      "oneOf": [
        {
          "type": "number",
          "minimum": 0
        },
        {
          "$ref": "#/$defs/modality_costs"
        }
      ]
    },
    "modality_costs": {
      "type": "object",
      "description": "Modality-specific token prices in USD per 1,000,000 tokens.",
      "properties": {
        "text": {
          "description": "Text token cost in USD per 1,000,000 tokens.",
          "type": "number",
          "minimum": 0
        },
        "image": {
          "description": "Image token cost in USD per 1,000,000 tokens.",
          "type": "number",
          "minimum": 0
        },
        "audio": {
          "description": "Audio token cost in USD per 1,000,000 tokens.",
          "type": "number",
          "minimum": 0
        },
        "video": {
          "description": "Video token cost in USD per 1,000,000 tokens.",
          "type": "number",
          "minimum": 0
        },
        "other": {
          "description": "Other or provider-specific token cost in USD per 1,000,000 tokens.",
          "type": "number",
          "minimum": 0
        }
      },
      "additionalProperties": false,
      "minProperties": 1
    },
    "tokenizer_config": {
      "type": "object",
      "description": "Tokenizer family and the specific encoding/version identifier within that family",
      "properties": {
        "family": {
          "description": "Tokenizer library or system (example: tiktoken, tekken, sentencepiece)",
          "type": "string",
          "enum": [
            "tiktoken",
            "tekken",
            "sentencepiece",
            "huggingface",
            "other",
            "unknown"
          ]
        },
        "name": {
          "description": "The encoding or version identifier within the family (example: 'cl100k_base' for tiktoken, 'v3' for tekken)",
          "type": "string"
        }
      },
      "required": ["family"]
    }
  }
}