{% include site-schema.html %}
Namespace Reference · Vocabulary

# tap: namespace

Stable IRI `https://taprun.dev/ns#`

The `tap:` namespace extends Schema.org with the operational metadata that machine-executable interface programs (taps) need but that Schema.org doesn't standardise — fingerprints, capture timestamps, extraction strategy, selector populations, endpoint shape hashes.

Every tap generated by Tap emits a `{name}.jsonld` manifest co-located with the tap source. The public surface of that manifest (provider, action, item list, required fields) is pure Schema.org. The operational metadata (fingerprint, strategy, selectors, endpoints) lives under this namespace. A consumer that only understands Schema.org sees a perfectly valid `WebAPI` declaration; a Tap-aware consumer sees the operational layer too.

## Classes

Term | IRI | Description
--- | --- | ---
`Tap` | tap:Tap | Marker class — co-asserted with `schema:WebAPI` to identify a Tap manifest.
`Fingerprint` | tap:Fingerprint | A point-in-time semantic structure capture of the target page (selectors, endpoints, globals). Used by doctor for drift detection.
`Selector` | tap:Selector | A CSS selector with a population count and an ARIA-based semantic hash.
`Endpoint` | tap:Endpoint | An observed network endpoint with response shape hash.
`Global` | tap:Global | An SSR/hydration global (e.g. `__NEXT_DATA__`) with its top-level keys.

## Properties

Term | IRI | Range | Description
--- | --- | --- | ---
`fingerprint` | tap:fingerprint | tap:Fingerprint | The captured fingerprint, attached to a tap:Tap.
`strategy` | tap:strategy | IRI | One of `tap:api`, `tap:dom`, `tap:ssr`, `tap:unknown`.
`capturedAt` | tap:capturedAt | xsd:dateTime | ISO 8601 timestamp of fingerprint capture.
`capturedBy` | tap:capturedBy | string | Trigger that produced this capture (e.g. `forge.verify@score=0.85`).
`rootHash` | tap:rootHash | string | FNV-1a Merkle root over all sub-hashes — O(1) "did anything change" check.
`selectors` | tap:selectors | set of tap:Selector | The captured selector population.
`endpoints` | tap:endpoints | set of tap:Endpoint | The captured network endpoints.
`globals` | tap:globals | set of tap:Global | The captured SSR/hydration globals.
`css` | tap:css | string | CSS selector text on a tap:Selector.
`count` | tap:count | xsd:integer | Element count for a tap:Selector.
`semanticHash` | tap:semanticHash | string | Hash of resolved ARIA roles + relationships at the selector — drift-resistant vs CSS class hashes.
`url` | tap:url | string | Endpoint URL.
`status` | tap:status | xsd:integer | HTTP status observed during capture.
`shapeHash` | tap:shapeHash | string | Hash of an endpoint's JSON response shape (keys + types).

## JSON-LD context

The machine-readable context document is embedded below. Tap manifests reference it via `"@context": ["https://schema.org", { "tap": "https://taprun.dev/ns#" }]`. Tap's own consumers parse `tap:`-prefixed fields by literal key (no remote context resolution), so this document exists primarily as a stable identifier and as documentation for external consumers.

## Example manifest

    {
      "@context": [
        "https://schema.org",
        { "tap": "https://taprun.dev/ns#" }
      ],
      "@type": ["WebAPI", "tap:Tap"],
      "@id": "tap:github/trending",
      "name": "github/trending",
      "description": "Trending GitHub repos for the day",
      "provider": {
        "@type": "Organization",
        "@id": "https://github.com",
        "name": "github.com"
      },
      "potentialAction": {
        "@type": "ReadAction",
        "target": {
          "@type": "EntryPoint",
          "urlTemplate": "https://github.com/trending",
          "httpMethod": "GET"
        },
        "object": {
          "@type": "ItemList",
          "numberOfItems": { "@type": "QuantitativeValue", "minValue": 5 },
          "itemListElement": {
            "@type": "ListItem",
            "additionalProperty": [
              { "@type": "PropertyValue", "name": "repo",  "valueRequired": true },
              { "@type": "PropertyValue", "name": "stars", "valueRequired": true },
              { "@type": "PropertyValue", "name": "language" }
            ]
          }
        }
      },
      "tap:fingerprint": {
        "@type": "tap:Fingerprint",
        "tap:capturedAt": "2026-04-08T09:33:00Z",
        "tap:strategy": "tap:api",
        "tap:rootHash": "abc123def",
        "tap:selectors": [
          {
            "@type": "tap:Selector",
            "tap:css": "article.Box-row",
            "tap:count": 25,
            "tap:semanticHash": "h1>a+span+p"
          }
        ]
      }
    }

◈

For source, runtime, and the rest of the Tap project see github.com/LeonTing1010/tap and taprun.dev.