Skip to content
OATSCHEMA

Docs / Schemas / ranking

Ranking 0.8.0

Represent a ranked list of items related to a query, such as search results, retrieved passages, recommendations or near-duplicate matches.

$id
https://oatschema.org/0.8.0/ranking
Latest
https://oatschema.org/ranking
Versions
  • 0.8.0
Source
v0.8.0 on GitHub

Schema

ranking.json Raw 
{    "x-license": {        "id": "Apache-2.0",        "notice": "Copyright 2025-2026 The OATS Authors",        "url": "https://github.com/oatschema/oats/blob/main/LICENSE"    },    "$schema": "https://json-schema.org/draft/2020-12/schema",    "$id": "https://oatschema.org/0.8.0/ranking",    "title": "Ranking",    "x-version": "0.8.0",    "description": "Represent a ranked list of items related to a query, such as search results, retrieved passages, recommendations or near-duplicate matches.",    "type": "object",    "properties": {        "target": {            "type": "string",            "description": "What the ranking measures (e.g., 'relevance', 'near-duplicate', 'recording-match').",            "maxLength": 256        },        "producer": {            "type": "string",            "description": "The creator (model, tool or author) of this ranking.",            "maxLength": 1024        },        "query": {            "type": "string",            "description": "The text of the query, if there was one. Omitted when there was no text query (e.g. near-duplicates of a given image, or recommendations for a user).",            "maxLength": 4096        },        "collection": {            "type": "string",            "description": "The name of the set the ranked items were drawn from, such as a search index, document collection or product catalogue (e.g., 'lease-agreements').",            "maxLength": 1024        },        "score_explanation": {            "type": "string",            "description": "Defines the meaning of the 'score' field.",            "maxLength": 256        },        "total_candidates": {            "type": "integer",            "description": "The number of candidates considered before the list was cut down to 'results'. Must not be less than the number of results, or than any result's rank.",            "minimum": 0        },        "results": {            "type": "array",            "description": "The ranked items. Can be empty if nothing matched.",            "maxItems": 10000,            "items": {                "type": "object",                "description": "A single ranked item.",                "properties": {                    "rank": {                        "type": "integer",                        "description": "The position of this item in the full ranking, where 1 is the best match. Tied items share a rank, and gaps are allowed (e.g. after a tie, or when results are filtered or paginated). The order of the items is given by 'rank', not by their order in the array.",                        "minimum": 1                    },                    "id": {                        "type": "string",                        "description": "An identifier for the item, such as a document id within 'collection' or a URI that resolves to it. Must be unique within 'results'.",                        "maxLength": 2048                    },                    "title": {                        "type": "string",                        "description": "A human-readable name for the item.",                        "maxLength": 1024                    },                    "text": {                        "type": "string",                        "description": "An excerpt of the item's text, such as a search snippet or a retrieved passage. May be truncated; 'id' identifies the full item.",                        "maxLength": 4096                    },                    "score": {                        "type": "number",                        "description": "A normalized score for this item (-1.0 to 1.0). Higher values indicate greater relevance or similarity. Depending on the use case, this may represent a probability of relevance (0 to 1) or a signed similarity such as cosine similarity (-1 to 1). Use score_explanation to clarify.",                        "minimum": -1,                        "maximum": 1                    },                    "attributes": {                        "type": "object",                        "description": "Arbitrary metadata for this item (e.g. a native score or distance, or the matched offset within a recording). Flat key-value pairs.",                        "maxProperties": 16,                        "propertyNames": {                            "maxLength": 128                        },                        "additionalProperties": {                            "anyOf": [                                {                                    "type": "string",                                    "maxLength": 1024                                },                                {                                    "type": "number"                                },                                {                                    "type": "boolean"                                },                                {                                    "type": "null"                                }                            ]                        }                    }                },                "required": [                    "rank",                    "id"                ],                "additionalProperties": false            }        },        "attributes": {            "type": "object",            "description": "Arbitrary metadata relevant to this ranking.",            "maxProperties": 16,            "propertyNames": {                "maxLength": 128            },            "additionalProperties": {                "anyOf": [                    {                        "type": "string",                        "maxLength": 1024                    },                    {                        "type": "number"                    },                    {                        "type": "boolean"                    },                    {                        "type": "null"                    }                ]            }        }    },    "required": [        "results"    ],    "additionalProperties": false}

Examples

Records that pass validation against this schema.

ranking-3
ranking-3.json 
{  "target": "recording-match",  "producer": "Chromaprint 1.5 + AcoustID",  "collection": "musicbrainz-recordings",  "score_explanation": "AcoustID match score.",  "results": [    {      "rank": 1,      "id": "b1a9c0e9-d987-4042-ae91-78d6a3267d69",      "title": "Clair de lune",      "score": 0.94,      "attributes": {        "offset_seconds": 92.5,        "matched_seconds": 18.0      }    }  ]}
ranking-1
ranking-1.json 
{  "target": "near-duplicate",  "producer": "imagehash 4.3 (pHash)",  "score_explanation": "1 - (Hamming distance / 64).",  "results": [    {      "rank": 1,      "id": "photos/2024/IMG_0412.jpg",      "score": 0.969,      "attributes": {        "hamming_distance": 2      }    },    {      "rank": 2,      "id": "photos/2024/IMG_0415.jpg",      "score": 0.859,      "attributes": {        "hamming_distance": 9      }    }  ]}
ranking-2
ranking-2.json 
{  "target": "relevance",  "producer": "text-embedding-3-small",  "query": "How much notice is needed to end the lease?",  "collection": "lease-agreements",  "score_explanation": "Cosine similarity.",  "results": [    {      "rank": 1,      "id": "https://wiki.example.org/leases/193#12",      "title": "Termination by the Tenant",      "text": "Two months' written notice is required.",      "score": 0.83    },    {      "rank": 2,      "id": "https://wiki.example.org/leases/193#14",      "title": "Break Clause",      "text": "Either party may end the lease early.",      "score": 0.71    }  ]}
ranking-4
ranking-4.json 
{  "target": "relevance",  "producer": "bge-reranker-v2-m3",  "query": "waterproof trail running shoes",  "collection": "products",  "score_explanation": "Sigmoid of the reranker logit.",  "total_candidates": 100,  "results": [    {      "rank": 1,      "id": "sku-48213",      "title": "Ridgeline GTX Trail Runner",      "score": 0.982,      "attributes": {        "logit": 4.0      }    },    {      "rank": 2,      "id": "sku-51007",      "title": "Fellrunner Waterproof",      "score": 0.924,      "attributes": {        "logit": 2.5      }    },    {      "rank": 2,      "id": "sku-50110",      "title": "Stormpath Trail Shoe",      "score": 0.924,      "attributes": {        "logit": 2.5      }    }  ]}

Fields

  • target string

    What the ranking measures (e.g., 'relevance', 'near-duplicate', 'recording-match').

    • at most 256 characters
  • producer string

    The creator (model, tool or author) of this ranking.

    • at most 1024 characters
  • query string

    The text of the query, if there was one. Omitted when there was no text query (e.g. near-duplicates of a given image, or recommendations for a user).

    • at most 4096 characters
  • collection string

    The name of the set the ranked items were drawn from, such as a search index, document collection or product catalogue (e.g., 'lease-agreements').

    • at most 1024 characters
  • score_explanation string

    Defines the meaning of the 'score' field.

    • at most 256 characters
  • total_candidates integer

    The number of candidates considered before the list was cut down to 'results'. Must not be less than the number of results, or than any result's rank.

    • ≥ 0
  • results array of object required

    The ranked items. Can be empty if nothing matched.

    Each item: A single ranked item.

    • at most 10000 items
    • rank integer required

      The position of this item in the full ranking, where 1 is the best match. Tied items share a rank, and gaps are allowed (e.g. after a tie, or when results are filtered or paginated). The order of the items is given by 'rank', not by their order in the array.

      • ≥ 1
    • id string required

      An identifier for the item, such as a document id within 'collection' or a URI that resolves to it. Must be unique within 'results'.

      • at most 2048 characters
    • title string

      A human-readable name for the item.

      • at most 1024 characters
    • text string

      An excerpt of the item's text, such as a search snippet or a retrieved passage. May be truncated; 'id' identifies the full item.

      • at most 4096 characters
    • score number

      A normalized score for this item (-1.0 to 1.0). Higher values indicate greater relevance or similarity. Depending on the use case, this may represent a probability of relevance (0 to 1) or a signed similarity such as cosine similarity (-1 to 1). Use score_explanation to clarify.

      • -1 to 1
    • attributes object

      Arbitrary metadata for this item (e.g. a native score or distance, or the matched offset within a recording). Flat key-value pairs.

      • at most 16 properties
      • keys at most 128 characters
      • * string | number | boolean | null

        Any other key.

        • string: at most 1024 characters
  • attributes object

    Arbitrary metadata relevant to this ranking.

    • at most 16 properties
    • keys at most 128 characters
    • * string | number | boolean | null

      Any other key.

      • string: at most 1024 characters

Copyright 2025-2026 The OATS Authors. Licensed under Apache-2.0.