{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.runlocal.ai/schemas/v1/operator-extension.json",
  "title": "Operator extension specification",
  "description": "A runlocal.operator-extension/1.0 specification. It defines one custom operator without relying on an external link. The authority field states whether this document or the pinned reference implementation defines behavior.",
  "type": "object",
  "required": [
    "kind",
    "protocol_version",
    "name",
    "version",
    "authority",
    "operator",
    "inputs",
    "outputs",
    "type_parameters",
    "attributes",
    "input_conditions",
    "shape_rules",
    "boundary_behavior",
    "numerical_behavior",
    "nondeterminism",
    "state_effects",
    "reference",
    "tests"
  ],
  "properties": {
    "kind": {
      "description": "The document kind.",
      "type": "string",
      "const": "runlocal.operator-extension"
    },
    "protocol_version": {
      "description": "The operator-extension document version.",
      "type": "string",
      "const": "1.0"
    },
    "name": {
      "$ref": "#/$defs/Name"
    },
    "version": {
      "description": "The version of this extension specification.",
      "type": "string",
      "minLength": 1
    },
    "authority": {
      "description": "specification: this document defines behavior. reference_implementation: the pinned implementation, under its declared environment, defines behavior on the stated input domain.",
      "type": "string",
      "enum": [
        "specification",
        "reference_implementation"
      ]
    },
    "operator": {
      "$ref": "#/$defs/OperatorIdentity"
    },
    "inputs": {
      "description": "Inputs in operator order.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/Parameter"
      }
    },
    "outputs": {
      "description": "Outputs in operator order.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/Parameter"
      }
    },
    "type_parameters": {
      "description": "Type constraints by parameter name.",
      "type": "object",
      "propertyNames": {
        "$ref": "#/$defs/Name"
      },
      "additionalProperties": {
        "$ref": "#/$defs/TypeParameter"
      }
    },
    "attributes": {
      "description": "Attributes by graph attribute name.",
      "type": "object",
      "propertyNames": {
        "$ref": "#/$defs/Name"
      },
      "additionalProperties": {
        "$ref": "#/$defs/AttributeDefinition"
      }
    },
    "input_conditions": {
      "description": "Conditions every valid input must meet.",
      "type": "array",
      "items": {
        "description": "A complete description in plain text.",
        "type": "string",
        "minLength": 1
      }
    },
    "shape_rules": {
      "description": "Rules that derive or constrain output shapes.",
      "type": "array",
      "items": {
        "description": "A complete description in plain text.",
        "type": "string",
        "minLength": 1
      }
    },
    "boundary_behavior": {
      "description": "A complete description in plain text.",
      "type": "string",
      "minLength": 1
    },
    "numerical_behavior": {
      "description": "A complete description in plain text.",
      "type": "string",
      "minLength": 1
    },
    "nondeterminism": {
      "description": "A complete description in plain text.",
      "type": "string",
      "minLength": 1
    },
    "state_effects": {
      "description": "A complete description in plain text.",
      "type": "string",
      "minLength": 1
    },
    "reference": {
      "description": "A pinned reference adapter and execution environment, or null. Its authority is set by the authority field.",
      "anyOf": [
        {
          "$ref": "#/$defs/ReferenceAdapter"
        },
        {
          "type": "null"
        }
      ]
    },
    "tests": {
      "description": "Bundled evidence files that test the specification. The list may be empty.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/Name"
      }
    }
  },
  "additionalProperties": false,
  "$defs": {
    "AttributeDefinition": {
      "title": "AttributeDefinition",
      "description": "One named attribute, including whether it is required, its default, and any exact allowed values.",
      "type": "object",
      "required": [
        "kind",
        "required",
        "default",
        "allowed_values",
        "description"
      ],
      "properties": {
        "kind": {
          "description": "The attribute value kind used by runlocal.graph.",
          "type": "string",
          "enum": [
            "int",
            "ints",
            "float",
            "floats",
            "string",
            "strings",
            "tensor",
            "tensors",
            "sparse_tensor",
            "sparse_tensors",
            "graph",
            "graphs",
            "type",
            "types"
          ]
        },
        "required": {
          "description": "true when every node must write the attribute.",
          "type": "boolean"
        },
        "default": {
          "description": "The default JSON value, or null when no default exists.",
          "anyOf": [
            {
              "description": "The default JSON value."
            },
            {
              "type": "null"
            }
          ]
        },
        "allowed_values": {
          "description": "The exact allowed values, or null when the signature does not restrict the value to a finite set.",
          "anyOf": [
            {
              "description": "The exact JSON values a node may supply. Members are unique and sorted by their canonical JSON bytes.",
              "type": "array",
              "minItems": 1,
              "uniqueItems": true,
              "x-runlocal-set": true,
              "items": {}
            },
            {
              "type": "null"
            }
          ]
        },
        "description": {
          "description": "A complete description in plain text.",
          "type": "string",
          "minLength": 1
        }
      },
      "additionalProperties": false
    },
    "ExactVersion": {
      "title": "ExactVersion",
      "description": "One exact release version. Ranges, wildcards, URLs, paths, and environment markers are not allowed.",
      "type": "string",
      "pattern": "^(?:[1-9][0-9]*!)?(?:0|[1-9][0-9]*)(?:\\.(?:0|[1-9][0-9]*))*(?:(?:a|b|rc)(?:0|[1-9][0-9]*))?(?:\\.post(?:0|[1-9][0-9]*))?(?:\\.dev(?:0|[1-9][0-9]*))?(?:\\+[a-z0-9]+(?:\\.[a-z0-9]+)*)?(?![\\s\\S])"
    },
    "Name": {
      "title": "Name",
      "description": "A stable name: a letter followed by letters, digits, underscores, dots, or hyphens.",
      "type": "string",
      "pattern": "^[A-Za-z][A-Za-z0-9_.-]{0,127}$"
    },
    "NativeReferenceEnvironment": {
      "title": "NativeReferenceEnvironment",
      "description": "The exact native environment that can load a custom-operator library.",
      "type": "object",
      "required": [
        "kind",
        "operating_system",
        "architecture",
        "libraries"
      ],
      "properties": {
        "kind": {
          "description": "Always \"native\". Selects this alternative.",
          "type": "string",
          "const": "native"
        },
        "operating_system": {
          "description": "The required operating system.",
          "type": "string",
          "enum": [
            "linux",
            "macos",
            "windows"
          ]
        },
        "architecture": {
          "description": "The required processor architecture.",
          "type": "string",
          "minLength": 1
        },
        "libraries": {
          "description": "Every runtime library the adapter needs, with its exact version.",
          "type": "object",
          "propertyNames": {
            "$ref": "#/$defs/PackageName"
          },
          "additionalProperties": {
            "$ref": "#/$defs/ExactVersion"
          }
        }
      },
      "additionalProperties": false
    },
    "OnnxReferencePython": {
      "title": "OnnxReferencePython",
      "description": "An OpRun adapter loaded through ReferenceEvaluator(new_ops=[...]). The adapter wraps the bundled implementation files.",
      "type": "object",
      "required": [
        "kind",
        "interface_version",
        "adapter",
        "class_name",
        "implementation",
        "environment"
      ],
      "properties": {
        "kind": {
          "description": "Always \"onnx.reference_python\". Selects this alternative.",
          "type": "string",
          "const": "onnx.reference_python"
        },
        "interface_version": {
          "description": "The first Runlocal profile for ONNX ReferenceEvaluator new_ops adapters.",
          "type": "string",
          "const": "1"
        },
        "adapter": {
          "$ref": "#/$defs/Name"
        },
        "class_name": {
          "$ref": "#/$defs/Name"
        },
        "implementation": {
          "description": "Bundled upstream implementation files that the adapter wraps. Members are unique and sorted by their canonical JSON bytes.",
          "type": "array",
          "uniqueItems": true,
          "x-runlocal-set": true,
          "items": {
            "$ref": "#/$defs/Name"
          }
        },
        "environment": {
          "$ref": "#/$defs/PythonReferenceEnvironment"
        }
      },
      "additionalProperties": false
    },
    "OnnxRuntimeCustomLibrary": {
      "title": "OnnxRuntimeCustomLibrary",
      "description": "A shared library registered through ONNX Runtime session options. This is separate from an ONNX Python reference adapter.",
      "type": "object",
      "required": [
        "kind",
        "interface_version",
        "library",
        "registration_symbol",
        "environment"
      ],
      "properties": {
        "kind": {
          "description": "Always \"onnxruntime.custom_library\". Selects this alternative.",
          "type": "string",
          "const": "onnxruntime.custom_library"
        },
        "interface_version": {
          "description": "The first Runlocal profile for ONNX Runtime custom-operator libraries.",
          "type": "string",
          "const": "1"
        },
        "library": {
          "$ref": "#/$defs/Name"
        },
        "registration_symbol": {
          "description": "The symbol an ONNX Runtime custom-operator library exports.",
          "type": "string",
          "const": "RegisterCustomOps"
        },
        "environment": {
          "$ref": "#/$defs/NativeReferenceEnvironment"
        }
      },
      "additionalProperties": false
    },
    "OperatorIdentity": {
      "title": "OperatorIdentity",
      "description": "The custom operator this specification defines.",
      "type": "object",
      "required": [
        "domain",
        "op_type",
        "overload"
      ],
      "properties": {
        "domain": {
          "description": "The operator domain as a graph spells it.",
          "type": "string"
        },
        "op_type": {
          "description": "The operator type name.",
          "type": "string",
          "minLength": 1
        },
        "overload": {
          "description": "The overload, or an empty string.",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "PackageName": {
      "title": "PackageName",
      "description": "A normalized lowercase package or library name.",
      "type": "string",
      "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?![\\s\\S])",
      "maxLength": 128
    },
    "Parameter": {
      "title": "Parameter",
      "description": "One input or output in operator order.",
      "type": "object",
      "required": [
        "name",
        "cardinality",
        "type_parameter",
        "description"
      ],
      "properties": {
        "name": {
          "$ref": "#/$defs/Name"
        },
        "cardinality": {
          "description": "single: one value is required. optional: zero or one value. variadic: zero or more values.",
          "type": "string",
          "enum": [
            "single",
            "optional",
            "variadic"
          ]
        },
        "type_parameter": {
          "description": "The type parameter that constrains this value, or null when the specification states its type another way.",
          "anyOf": [
            {
              "$ref": "#/$defs/Name"
            },
            {
              "type": "null"
            }
          ]
        },
        "description": {
          "description": "A complete description in plain text.",
          "type": "string",
          "minLength": 1
        }
      },
      "additionalProperties": false
    },
    "PythonReferenceEnvironment": {
      "title": "PythonReferenceEnvironment",
      "description": "The exact Python environment that gives the reference implementation its declared behavior.",
      "type": "object",
      "required": [
        "kind",
        "python",
        "packages"
      ],
      "properties": {
        "kind": {
          "description": "Always \"python\". Selects this alternative.",
          "type": "string",
          "const": "python"
        },
        "python": {
          "$ref": "#/$defs/ExactVersion"
        },
        "packages": {
          "description": "Every Python package the adapter and implementation import, with its exact installed version.",
          "type": "object",
          "propertyNames": {
            "$ref": "#/$defs/PackageName"
          },
          "additionalProperties": {
            "$ref": "#/$defs/ExactVersion"
          }
        }
      },
      "additionalProperties": false
    },
    "ReferenceAdapter": {
      "title": "ReferenceAdapter",
      "description": "A versioned runtime interface for the reference implementation.",
      "oneOf": [
        {
          "$ref": "#/$defs/OnnxReferencePython"
        },
        {
          "$ref": "#/$defs/OnnxRuntimeCustomLibrary"
        }
      ],
      "discriminator": {
        "mapping": {
          "onnx.reference_python": "#/$defs/OnnxReferencePython",
          "onnxruntime.custom_library": "#/$defs/OnnxRuntimeCustomLibrary"
        },
        "propertyName": "kind"
      }
    },
    "ReferenceEnvironment": {
      "title": "ReferenceEnvironment",
      "description": "The pinned environment required by a reference adapter.",
      "oneOf": [
        {
          "$ref": "#/$defs/PythonReferenceEnvironment"
        },
        {
          "$ref": "#/$defs/NativeReferenceEnvironment"
        }
      ],
      "discriminator": {
        "mapping": {
          "python": "#/$defs/PythonReferenceEnvironment",
          "native": "#/$defs/NativeReferenceEnvironment"
        },
        "propertyName": "kind"
      }
    },
    "TypeParameter": {
      "title": "TypeParameter",
      "description": "A named type constraint used by inputs or outputs.",
      "type": "object",
      "required": [
        "allowed_types",
        "description"
      ],
      "properties": {
        "allowed_types": {
          "description": "The allowed ONNX type expressions.",
          "type": "array",
          "minItems": 1,
          "items": {
            "description": "One allowed ONNX type expression, such as tensor(float).",
            "type": "string",
            "minLength": 1
          }
        },
        "description": {
          "description": "A complete description in plain text.",
          "type": "string",
          "minLength": 1
        }
      },
      "additionalProperties": false
    }
  }
}