{
  "system": "GoGuides Web State Semantics",
  "contract": "web-state-v3",
  "contract_version": "3.0",
  "status": "active",
  "canonical_url": "https://www.goguides.com/docs/web-state.json",

  "purpose": "Machine-readable semantics for GoGuides Web State V3 fields and bitmasks.",

  "interpretation": {
    "principle": "Values describe observations made by the GoGuides collector. Consumers should not infer claims beyond the documented scope of each field.",
    "null": "Value was unavailable, not observed, not applicable, or not stored for that observation.",
    "zero": "Zero is a valid observed value and must not be interpreted as null or missing.",
    "omitted_field": "A field may be omitted from a public State response when its stored value is null.",
    "unknown_bits": "Consumers must ignore unknown bit positions they do not understand and may inspect decoded unknown_bits when supplied by the State endpoint.",
    "forward_compatibility": "New meanings require new documented bit positions or a new mask version. Existing published bit meanings must not be silently redefined."
  },

  "state_endpoint": {
    "template": "https://www.goguides.com/state/{domain}",
    "api_version": "web-state-v3",
    "scope": "objective_web_state_v3",
    "content_type": "application/json",
    "description": "Returns the latest publicly eligible objective Web State observation available for a domain."
  },

  "evaluate_endpoint": {
    "template": "https://www.goguides.com/evaluate/{domain}",
    "api_version": "evaluate-v3.2",
    "description": "Evaluates a domain and advertises state_url plus the Web State semantics contract when State discovery is available."
  },

  "fields": {
    "text_simhash": {
      "type": "unsigned_64_bit_integer_encoded_as_decimal_string",
      "nullable": true,
      "description": "Bounded 64-bit SimHash derived from normalized observed page text. Intended for efficient similarity and change comparison, not cryptographic integrity."
    },

    "structured_data_sha256": {
      "type": "sha256_hex",
      "nullable": true,
      "description": "SHA-256 of canonicalized parsed JSON-LD structured data observed on the page. Omitted when no canonical JSON-LD payload was stored."
    },

    "schema_type_mask": {
      "type": "unsigned_integer_bitmask",
      "nullable": true,
      "mask_version": "schema-type-mask-v1",
      "decoded_companion": "schema_types",
      "description": "Bitmask of recognized Schema.org @type values observed in parsed JSON-LD."
    },

    "headers_sha256": {
      "type": "sha256_hex",
      "nullable": true,
      "description": "SHA-256 of the normalized selected response-header set used by the Web State collector."
    },

    "word_count": {
      "type": "unsigned_integer",
      "nullable": true,
      "description": "Observed normalized text word count, bounded to the collector storage range."
    },

    "internal_link_count": {
      "type": "unsigned_integer",
      "nullable": true,
      "description": "Count of normalized links classified as internal to the observed site."
    },

    "external_link_count": {
      "type": "unsigned_integer",
      "nullable": true,
      "description": "Count of normalized links classified as external to the observed site."
    },

    "outbound_links_sha256": {
      "type": "sha256_hex",
      "nullable": true,
      "description": "SHA-256 representing the normalized observed outbound link set."
    },

    "ai_policy_mask": {
      "type": "unsigned_integer_bitmask",
      "nullable": true,
      "mask_version": "ai-policy-mask-v1",
      "decoded_companion": "ai_policy",
      "description": "Compact mask of crawler-policy results and machine-facing directives observed by the GoGuides collector."
    }
  },

  "ai_policy_mask": {
    "version": "ai-policy-mask-v1",
    "scope": "observed_machine_directives",
    "robots_agent": "GoGuidesCrawler",

    "important": [
      "The robots crawl decision represented by bits 0 through 3 is the decision made for GoGuidesCrawler.",
      "The mask does not claim robots.txt permission or denial for GPTBot, ClaudeBot, MetaExternalAgent, or any other external crawler.",
      "META robots bits record directives observed in the page source.",
      "X-Robots-Tag bits record directives observed in response headers.",
      "An X-Robots-Tag header can contain agent-specific syntax; presence of a directive does not mean that directive applies to every external crawler."
    ],

    "bits": {
      "0": {
        "value": 1,
        "name": "goguides_crawler_allowed",
        "meaning": "GoGuidesCrawler allowed by robots check"
      },
      "1": {
        "value": 2,
        "name": "goguides_crawler_disallowed",
        "meaning": "GoGuidesCrawler disallowed by robots check"
      },
      "2": {
        "value": 4,
        "name": "robots_unreachable_allowed",
        "meaning": "robots.txt unreachable; crawl allowed"
      },
      "3": {
        "value": 8,
        "name": "robots_check_failed_allowed",
        "meaning": "robots check failed; crawl allowed"
      },
      "4": {
        "value": 16,
        "name": "meta_noindex",
        "meaning": "META robots noindex observed"
      },
      "5": {
        "value": 32,
        "name": "meta_nofollow",
        "meaning": "META robots nofollow observed"
      },
      "6": {
        "value": 64,
        "name": "meta_nosnippet",
        "meaning": "META robots nosnippet observed"
      },
      "7": {
        "value": 128,
        "name": "meta_noarchive",
        "meaning": "META robots noarchive observed"
      },
      "8": {
        "value": 256,
        "name": "x_robots_noindex",
        "meaning": "X-Robots-Tag noindex observed"
      },
      "9": {
        "value": 512,
        "name": "x_robots_nofollow",
        "meaning": "X-Robots-Tag nofollow observed"
      },
      "10": {
        "value": 1024,
        "name": "x_robots_nosnippet",
        "meaning": "X-Robots-Tag nosnippet observed"
      },
      "11": {
        "value": 2048,
        "name": "x_robots_noarchive",
        "meaning": "X-Robots-Tag noarchive observed"
      }
    },

    "decode": {
      "rule": "A bit is set when (mask & value) == value.",
      "zero": "Mask 0 means none of the documented bits are set.",
      "unknown": "Set bits not defined by the declared mask version must be treated as unknown rather than assigned an inferred meaning."
    }
  },

  "schema_type_mask": {
    "version": "schema-type-mask-v1",
    "source_vocabulary": "Schema.org",
    "observation_source": "Parsed application/ld+json",

    "bits": {
      "0":  { "value": 1,        "name": "Organization" },
      "1":  { "value": 2,        "name": "WebSite" },
      "2":  { "value": 4,        "name": "WebPage" },
      "3":  { "value": 8,        "name": "Article" },
      "4":  { "value": 16,       "name": "NewsArticle" },
      "5":  { "value": 32,       "name": "BlogPosting" },
      "6":  { "value": 64,       "name": "Product" },
      "7":  { "value": 128,      "name": "Dataset" },
      "8":  { "value": 256,      "name": "LocalBusiness" },
      "9":  { "value": 512,      "name": "Person" },
      "10": { "value": 1024,     "name": "FAQPage" },
      "11": { "value": 2048,     "name": "HowTo" },
      "12": { "value": 4096,     "name": "BreadcrumbList" },
      "13": { "value": 8192,     "name": "VideoObject" },
      "14": { "value": 16384,    "name": "ImageObject" },
      "15": { "value": 32768,    "name": "SoftwareApplication" },
      "16": { "value": 65536,    "name": "MobileApplication" },
      "17": { "value": 131072,   "name": "SearchAction" },
      "18": { "value": 262144,   "name": "Event" },
      "19": { "value": 524288,   "name": "JobPosting" },
      "20": { "value": 1048576,  "name": "Review" },
      "21": { "value": 2097152,  "name": "AggregateRating" },
      "22": { "value": 4194304,  "name": "Offer" },
      "23": { "value": 8388608,  "name": "Service" },
      "24": { "value": 16777216, "name": "Course" },
      "25": { "value": 33554432, "name": "Recipe" }
    },

    "decode": {
      "rule": "A Schema.org type is present when (mask & value) == value.",
      "zero": "Mask 0 means none of the recognized schema_type_mask-v1 types were observed.",
      "not_exhaustive": "The mask records only Schema.org types recognized by this contract version. It is not a complete representation of every possible Schema.org type.",
      "unknown": "Set bits not defined by the declared mask version must be treated as unknown."
    }
  },

  "decoded_companions": {
    "schema_types": {
      "fields": {
        "mask_version": "Declared schema mask contract version.",
        "set_bits": "Known bit positions set in schema_type_mask.",
        "types": "Recognized Schema.org type names represented by those bits.",
        "unknown_bits": "Set bit positions not understood by the current decoder.",
        "semantics_url": "Canonical machine-readable semantics resource."
      }
    },

    "ai_policy": {
      "fields": {
        "mask_version": "Declared AI policy mask contract version.",
        "scope": "Interpretation scope of the decoded policy flags.",
        "robots_agent": "Crawler identity used for the robots decision.",
        "set_bits": "Known bit positions set in ai_policy_mask.",
        "flags": "Stable symbolic names represented by those bits.",
        "unknown_bits": "Set bit positions not understood by the current decoder.",
        "semantics_url": "Canonical machine-readable semantics resource."
      }
    }
  },

  "example": {
    "schema_type_mask": 5,
    "schema_types": {
      "mask_version": "schema-type-mask-v1",
      "set_bits": [0, 2],
      "types": ["Organization", "WebPage"],
      "unknown_bits": []
    },

    "ai_policy_mask": 17,
    "ai_policy": {
      "mask_version": "ai-policy-mask-v1",
      "scope": "observed_machine_directives",
      "robots_agent": "GoGuidesCrawler",
      "set_bits": [0, 4],
      "flags": [
        "goguides_crawler_allowed",
        "meta_noindex"
      ],
      "unknown_bits": []
    }
  },

  "compatibility": {
    "raw_masks": "Raw integer masks remain part of the Web State V3 response for compact machine processing.",
    "decoded_objects": "Decoded companion objects are additive and do not replace raw masks.",
    "consumer_rule": "Consumers should use mask_version before assigning meaning to a bit position.",
    "extension_rule": "Consumers must tolerate additional response fields and previously unknown bit positions."
  },

  "links": {
    "evaluate": "https://www.goguides.com/evaluate/{domain}",
    "state": "https://www.goguides.com/state/{domain}",
    "history": "https://www.goguides.com/history/{domain}",
    "verify": "https://www.goguides.com/verify/{domain}",
    "machine_use": "https://www.goguides.com/machine-use.json",
    "data_license": "https://www.goguides.com/data-license"
  }
}