{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://macvendor.io/schemas/public-api-v1.schema.json",
  "title": "macvendor public API v1 schemas",
  "$defs": {
    "SourceReference": {
      "type": "object",
      "additionalProperties": false,
      "required": ["slug", "sourceReleaseId"],
      "properties": {
        "slug": { "type": "string", "minLength": 1 },
        "sourceReleaseId": { "type": "string", "pattern": "^sr_[0-9a-f-]+$" }
      }
    },
    "ReleaseData": {
      "type": "object",
      "additionalProperties": false,
      "required": ["resolvedReleaseId", "activeVersion", "publicationVersion", "policyVersion", "generatedAt"],
      "properties": {
        "resolvedReleaseId": { "type": "string", "pattern": "^rr_[0-9a-f-]+$" },
        "activeVersion": { "type": "integer", "minimum": 1 },
        "publicationVersion": { "type": "integer", "minimum": 1 },
        "policyVersion": { "type": "string", "minLength": 1 },
        "generatedAt": { "type": "string", "format": "date-time" }
      }
    },
    "Assignment": {
      "type": "object",
      "additionalProperties": false,
      "required": ["prefix", "prefixLength", "registry", "organizationName", "address", "source"],
      "properties": {
        "prefix": { "type": "string", "pattern": "^[0-9A-F]{6,9}$" },
        "prefixLength": { "type": "integer", "enum": [24, 28, 36] },
        "registry": { "type": "string", "enum": ["MA-L", "MA-M", "MA-S", "IAB", "CID"] },
        "organizationName": { "type": ["string", "null"] },
        "address": { "type": ["string", "null"] },
        "source": { "$ref": "#/$defs/SourceReference" }
      }
    },
    "CuratedMatch": {
      "type": "object",
      "additionalProperties": false,
      "required": ["claimId", "prefix", "prefixLength", "claimType", "organizationName", "verificationStatus", "originType", "conflictStatus", "source"],
      "properties": {
        "claimId": { "type": "string", "pattern": "^clm_[0-9a-f-]+$" },
        "prefix": { "type": "string", "pattern": "^[0-9A-F]{1,12}$" },
        "prefixLength": { "type": "integer", "minimum": 1, "maximum": 48 },
        "claimType": { "const": "vendor_label" },
        "organizationName": { "type": "string", "minLength": 1 },
        "verificationStatus": { "type": "string", "enum": ["reviewed", "corroborated", "single_observation", "unverified"] },
        "originType": { "type": "string", "enum": ["owner_observation", "derived", "imported"] },
        "conflictStatus": { "type": "string", "enum": ["agrees", "conflicts", "no_official_match", "not_evaluated"] },
        "source": { "$ref": "#/$defs/SourceReference" }
      }
    },
    "LookupInsight": {
      "type": "object",
      "additionalProperties": false,
      "required": ["claimId", "prefix", "prefixLength", "claimType", "organizationName", "details", "verificationStatus", "source"],
      "properties": {
        "claimId": { "type": "string", "pattern": "^clm_[0-9a-f-]+$" },
        "prefix": { "type": "string", "pattern": "^[0-9A-F]{1,12}$" },
        "prefixLength": { "type": "integer", "minimum": 1, "maximum": 48 },
        "claimType": { "type": "string", "enum": ["vendor_alias", "device_hint", "usage_note"] },
        "organizationName": { "type": ["string", "null"] },
        "details": { "type": "object" },
        "verificationStatus": { "type": "string", "enum": ["reviewed", "corroborated", "single_observation", "unverified"] },
        "source": { "$ref": "#/$defs/SourceReference" }
      }
    },
    "LookupResponse": {
      "type": "object",
      "additionalProperties": false,
      "required": ["query", "matchStatus", "assignment", "curatedMatches", "curatedMatchesTruncated", "insights", "insightsTruncated", "data"],
      "properties": {
        "query": {
          "type": "object",
          "additionalProperties": false,
          "required": ["input", "normalized", "flags"],
          "properties": {
            "input": { "type": "string", "pattern": "^[0-9A-F]{12}$" },
            "normalized": { "type": "string", "pattern": "^[0-9A-F]{12}$" },
            "flags": {
              "type": "object",
              "additionalProperties": false,
              "required": ["locallyAdministered", "multicast"],
              "properties": {
                "locallyAdministered": { "type": "boolean" },
                "multicast": { "type": "boolean" }
              }
            }
          }
        },
        "matchStatus": { "type": "string", "enum": ["matched", "no_match"] },
        "assignment": { "oneOf": [{ "$ref": "#/$defs/Assignment" }, { "type": "null" }] },
        "curatedMatches": { "type": "array", "maxItems": 20, "items": { "$ref": "#/$defs/CuratedMatch" } },
        "curatedMatchesTruncated": { "type": "boolean" },
        "insights": { "type": "array", "maxItems": 50, "items": { "$ref": "#/$defs/LookupInsight" } },
        "insightsTruncated": { "type": "boolean" },
        "data": { "$ref": "#/$defs/ReleaseData" }
      },
      "allOf": [
        { "if": { "properties": { "matchStatus": { "const": "no_match" } } }, "then": { "properties": { "assignment": { "type": "null" } } } },
        { "if": { "properties": { "matchStatus": { "const": "matched" } } }, "then": { "properties": { "assignment": { "$ref": "#/$defs/Assignment" } } } }
      ]
    },
    "BulkLookupItem": {
      "type": "object",
      "additionalProperties": false,
      "required": ["normalizedMac", "matchStatus", "assignment", "release"],
      "properties": {
        "normalizedMac": { "type": "string", "pattern": "^[0-9A-F]{12}$" },
        "matchStatus": { "type": "string", "enum": ["matched", "no_match"] },
        "assignment": { "oneOf": [{ "$ref": "#/$defs/Assignment" }, { "type": "null" }] },
        "release": { "$ref": "#/$defs/ReleaseData" }
      },
      "allOf": [
        { "if": { "properties": { "matchStatus": { "const": "no_match" } } }, "then": { "properties": { "assignment": { "type": "null" } } } },
        { "if": { "properties": { "matchStatus": { "const": "matched" } } }, "then": { "properties": { "assignment": { "$ref": "#/$defs/Assignment" } } } }
      ]
    },
    "BulkEnrichedLookupItem": {
      "type": "object",
      "additionalProperties": false,
      "required": ["normalizedMac", "matchStatus", "assignment", "release", "curatedMatches", "curatedMatchesTruncated", "insights", "insightsTruncated"],
      "properties": {
        "normalizedMac": { "type": "string", "pattern": "^[0-9A-F]{12}$" },
        "matchStatus": { "type": "string", "enum": ["matched", "no_match"] },
        "assignment": { "oneOf": [{ "$ref": "#/$defs/Assignment" }, { "type": "null" }] },
        "release": { "$ref": "#/$defs/ReleaseData" },
        "curatedMatches": { "type": "array", "maxItems": 20, "items": { "$ref": "#/$defs/CuratedMatch" } },
        "curatedMatchesTruncated": { "type": "boolean" },
        "insights": { "type": "array", "maxItems": 50, "items": { "$ref": "#/$defs/LookupInsight" } },
        "insightsTruncated": { "type": "boolean" }
      },
      "allOf": [
        { "if": { "properties": { "matchStatus": { "const": "no_match" } } }, "then": { "properties": { "assignment": { "type": "null" } } } },
        { "if": { "properties": { "matchStatus": { "const": "matched" } } }, "then": { "properties": { "assignment": { "$ref": "#/$defs/Assignment" } } } }
      ]
    },
    "BulkLookupResponse": {
      "oneOf": [
        {
          "type": "object", "additionalProperties": false, "required": ["data", "meta"],
          "properties": {
            "data": {
              "type": "object", "additionalProperties": false, "required": ["type", "mode", "results"],
              "properties": {
                "type": { "const": "bulk_lookup" }, "mode": { "const": "official" },
                "results": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/$defs/BulkLookupItem" } }
              }
            },
            "meta": {
              "type": "object", "additionalProperties": false, "required": ["requestId", "count", "uniqueCount"],
              "properties": {
                "requestId": { "type": "string", "minLength": 1 },
                "count": { "type": "integer", "minimum": 1, "maximum": 100 },
                "uniqueCount": { "type": "integer", "minimum": 1, "maximum": 100 }
              }
            }
          }
        },
        {
          "type": "object", "additionalProperties": false, "required": ["data", "meta"],
          "properties": {
            "data": {
              "type": "object", "additionalProperties": false, "required": ["type", "mode", "results"],
              "properties": {
                "type": { "const": "bulk_lookup" }, "mode": { "const": "enriched" },
                "results": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/$defs/BulkEnrichedLookupItem" } }
              }
            },
            "meta": {
              "type": "object", "additionalProperties": false, "required": ["requestId", "count", "uniqueCount"],
              "properties": {
                "requestId": { "type": "string", "minLength": 1 },
                "count": { "type": "integer", "minimum": 1, "maximum": 50 },
                "uniqueCount": { "type": "integer", "minimum": 1, "maximum": 50 }
              }
            }
          }
        }
      ]
    },
    "Evidence": {
      "type": "object",
      "additionalProperties": false,
      "required": ["evidenceId", "sourceSlug", "sourceReleaseId", "role", "reasonCode", "observedAt"],
      "properties": {
        "evidenceId": { "type": "string", "pattern": "^ev_[0-9a-f-]+$" },
        "sourceSlug": { "type": "string", "minLength": 1 },
        "sourceReleaseId": { "type": "string", "pattern": "^sr_[0-9a-f-]+$" },
        "role": { "type": "string", "enum": ["selected", "corroborating", "conflicting", "suppressed"] },
        "reasonCode": { "type": "string", "minLength": 1 },
        "observedAt": { "type": ["string", "null"], "format": "date-time" }
      }
    },
    "AssignmentResponse": {
      "type": "object",
      "additionalProperties": false,
      "required": ["assignment", "data"],
      "dependentRequired": { "evidence": ["evidenceTruncated"], "evidenceTruncated": ["evidence"] },
      "properties": {
        "assignment": { "$ref": "#/$defs/Assignment" },
        "data": { "$ref": "#/$defs/ReleaseData" },
        "evidence": { "type": "array", "maxItems": 100, "items": { "$ref": "#/$defs/Evidence" } },
        "evidenceTruncated": { "type": "boolean" }
      }
    },
    "DataReleaseResponse": {
      "type": "object",
      "additionalProperties": false,
      "required": ["resolvedReleaseId", "activeVersion", "publicationVersion", "policyVersion", "outputSha256", "generatedAt", "sources"],
      "properties": {
        "resolvedReleaseId": { "type": "string", "pattern": "^rr_[0-9a-f-]+$" },
        "activeVersion": { "type": "integer", "minimum": 1 },
        "publicationVersion": { "type": "integer", "minimum": 1 },
        "policyVersion": { "type": "string", "minLength": 1 },
        "outputSha256": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
        "generatedAt": { "type": "string", "format": "date-time" },
        "sources": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": ["slug", "sourceReleaseId", "observedAt", "verificationStatus", "sourceClass", "recordCount", "rightsScope", "rightsStatusAtBuild", "currentRightsStatus", "rightsReviewExpiresAt", "status", "configVersion", "configVersionAtBuild", "configChangedSinceBuild"],
            "properties": {
              "slug": { "type": "string", "minLength": 1 },
              "sourceReleaseId": { "type": "string", "pattern": "^sr_[0-9a-f-]+$" },
              "observedAt": { "type": "string", "format": "date-time" },
              "verificationStatus": { "type": "string", "enum": ["authoritative", "owner_asserted"] },
              "sourceClass": { "type": "string", "enum": ["authoritative", "enrichment", "owner_curated"] },
              "recordCount": { "type": "integer", "minimum": 0 },
              "rightsScope": { "type": "string", "enum": ["internal_only", "api_output", "raw_redistribution"] },
              "rightsStatusAtBuild": { "type": "string", "enum": ["unreviewed", "owner_asserted", "approved", "rejected", "expired"] },
              "currentRightsStatus": { "type": "string", "enum": ["unreviewed", "owner_asserted", "approved", "rejected", "expired"] },
              "rightsReviewExpiresAt": { "type": ["string", "null"], "format": "date-time" },
              "status": { "const": "included" },
              "configVersion": { "type": "integer", "minimum": 1 },
              "configVersionAtBuild": { "type": "integer", "minimum": 1 },
              "configChangedSinceBuild": { "type": "boolean" }
            }
          }
        }
      }
    },
    "ReleaseChangesResponse": {
      "type": "object", "additionalProperties": false, "required": ["current", "previous", "changes"],
      "properties": {
        "current": {
          "type": "object", "additionalProperties": false,
          "required": ["resolvedReleaseId", "activeVersion", "publicationVersion", "generatedAt"],
          "properties": {
            "resolvedReleaseId": { "type": "string", "pattern": "^rr_[0-9a-f-]+$" },
            "activeVersion": { "type": "integer", "minimum": 1 },
            "publicationVersion": { "type": "integer", "minimum": 1 },
            "generatedAt": { "type": "string", "format": "date-time" }
          }
        },
        "previous": { "oneOf": [{
          "type": "object", "additionalProperties": false, "required": ["resolvedReleaseId", "generatedAt"],
          "properties": { "resolvedReleaseId": { "type": "string", "pattern": "^rr_[0-9a-f-]+$" }, "generatedAt": { "type": "string", "format": "date-time" } }
        }, { "type": "null" }] },
        "changes": {
          "type": "object", "additionalProperties": false,
          "required": ["assignmentsAdded", "assignmentsRemoved", "assignmentsChanged", "claimsAdded", "claimsRemoved", "sourceReleasesChanged"],
          "properties": {
            "assignmentsAdded": { "type": "integer", "minimum": 0 }, "assignmentsRemoved": { "type": "integer", "minimum": 0 },
            "assignmentsChanged": { "type": "integer", "minimum": 0 }, "claimsAdded": { "type": "integer", "minimum": 0 },
            "claimsRemoved": { "type": "integer", "minimum": 0 }, "sourceReleasesChanged": { "type": "integer", "minimum": 0 }
          }
        }
      }
    },
    "Organization": {
      "type": "object",
      "additionalProperties": false,
      "required": ["organizationKey", "name", "aliases", "registeredNames", "externalIdentifiers", "assignments", "assignmentsTruncated"],
      "properties": {
        "organizationKey": { "type": "string", "minLength": 1, "maxLength": 80 },
        "name": { "type": "string", "minLength": 1 },
        "aliases": { "type": "array", "items": { "type": "string" } },
        "registeredNames": { "type": "array", "items": { "type": "string" } },
        "externalIdentifiers": { "type": "array", "items": { "$ref": "#/$defs/OrganizationIdentifier" } },
        "assignments": { "type": "array", "maxItems": 100, "items": { "$ref": "#/$defs/OrganizationAssignment" } },
        "assignmentsTruncated": { "type": "boolean" }
      }
    },
    "OrganizationIdentifier": {
      "type": "object",
      "additionalProperties": false,
      "required": ["scheme", "identifier", "source", "details"],
      "properties": {
        "scheme": { "type": "string", "minLength": 1, "maxLength": 80 },
        "identifier": { "type": "string", "minLength": 1, "maxLength": 200 },
        "source": { "$ref": "#/$defs/SourceReference" },
        "details": { "type": "object" }
      }
    },
    "OrganizationAssignment": {
      "type": "object",
      "additionalProperties": false,
      "required": ["registry", "prefix", "prefixLength", "organizationName"],
      "properties": {
        "registry": { "type": "string", "enum": ["MA-L", "MA-M", "MA-S", "IAB", "CID"] },
        "prefix": { "type": "string", "pattern": "^[0-9A-F]{1,12}$" },
        "prefixLength": { "type": "integer", "minimum": 1, "maximum": 48 },
        "organizationName": { "type": "string", "minLength": 1 }
      }
    },
    "OrganizationSearchResponse": {
      "type": "object",
      "additionalProperties": false,
      "required": ["query", "filters", "results", "truncated"],
      "properties": {
        "query": { "type": "string" },
        "filters": {
          "type": "object", "additionalProperties": false, "required": ["scheme", "registry"],
          "properties": {
            "scheme": { "type": ["string", "null"] },
            "registry": { "oneOf": [{ "type": "string", "enum": ["MA-L", "MA-M", "MA-S", "IAB"] }, { "type": "null" }] }
          }
        },
        "results": { "type": "array", "maxItems": 20, "items": { "$ref": "#/$defs/Organization" } },
        "truncated": { "type": "boolean" }
      }
    },
    "CorrectionRequest": {
      "type": "object",
      "additionalProperties": false,
      "required": ["category", "target", "requestedChange", "evidenceUrl", "contactEmail"],
      "properties": {
        "category": { "type": "string", "enum": ["incorrect_assignment", "incorrect_context", "privacy", "rights", "withdrawal"] },
        "target": { "type": "string", "minLength": 1, "maxLength": 128 },
        "requestedChange": { "type": "string", "minLength": 20, "maxLength": 2000 },
        "evidenceUrl": { "type": "string", "format": "uri", "pattern": "^https://" },
        "contactEmail": { "type": "string", "format": "email", "maxLength": 254 }
      }
    },
    "CorrectionAccepted": {
      "type": "object",
      "additionalProperties": false,
      "required": ["reference", "status", "receivedAt"],
      "properties": {
        "reference": { "type": "string", "pattern": "^CORR-[0-9]{8}-[A-F0-9]{8}$" },
        "status": { "const": "received" },
        "receivedAt": { "type": "string", "format": "date-time" }
      }
    },
    "Problem": {
      "type": "object",
      "additionalProperties": false,
      "required": ["type", "title", "status", "code", "detail", "requestId", "apiVersion", "appVersion"],
      "properties": {
        "type": { "type": "string", "format": "uri", "pattern": "^https://macvendor\\.io/problems/" },
        "title": { "type": "string", "minLength": 1 },
        "status": { "type": "integer", "enum": [400, 404, 413, 415, 429, 503] },
        "code": { "type": "string", "enum": ["INVALID_MAC", "INVALID_PREFIX", "INVALID_REGISTRY", "UNSUPPORTED_PARAMETER", "INVALID_JSON", "INVALID_BULK_REQUEST", "BULK_BODY_TOO_LARGE", "ASSIGNMENT_NOT_FOUND", "INVALID_ORGANIZATION_QUERY", "INVALID_ORGANIZATION_KEY", "ORGANIZATION_NOT_FOUND", "INVALID_CORRECTION_REQUEST", "PAYLOAD_TOO_LARGE", "UNSUPPORTED_MEDIA_TYPE", "CORRECTION_INTAKE_UNAVAILABLE", "RATE_LIMITED", "DATA_RELEASE_UNAVAILABLE", "SERVICE_UNAVAILABLE"] },
        "detail": { "type": "string", "minLength": 1 },
        "requestId": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,64}$" },
        "apiVersion": { "const": "v1" },
        "appVersion": { "type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$" }
      },
      "allOf": [
        {
          "if": { "properties": { "code": { "enum": ["INVALID_MAC", "INVALID_PREFIX", "INVALID_REGISTRY", "UNSUPPORTED_PARAMETER"] } } },
          "then": { "properties": { "status": { "const": 400 } } }
        },
        {
          "if": { "properties": { "code": { "const": "ASSIGNMENT_NOT_FOUND" } } },
          "then": { "properties": { "status": { "const": 404 } } }
        },
        {
          "if": { "properties": { "code": { "const": "RATE_LIMITED" } } },
          "then": { "properties": { "status": { "const": 429 } } }
        },
        {
          "if": { "properties": { "code": { "enum": ["DATA_RELEASE_UNAVAILABLE", "SERVICE_UNAVAILABLE"] } } },
          "then": { "properties": { "status": { "const": 503 } } }
        }
      ]
    }
  }
}