Bookable Specification

The base pattern for AI-bookable entities.

Abstract

Bookable defines the base pattern for any entity that AI agents can discover, understand, trust, and transact with. It is not a protocol—it is a pattern that domain-specific extensions inherit from.

1. Introduction

1.1 Purpose

AI agents making recommendations and bookings require structured, verifiable information to:

1. Determine whether an entity fits a user's intent
2. Defend the recommendation if challenged
3. Complete a transaction without friction

Bookable provides this structure in a domain-neutral form.

1.2 Scope

1.3 Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

2. Bookable Structure

A Bookable-conformant record MUST include:

{
  "bookable": {
    "schemaVersion": "0.1.0",
    "type": "string",
    "identity": { },
    "evidence": { },
    "fit": { },
    "actions": { }
  }
}

The presentation and answers blocks are RECOMMENDED but OPTIONAL.

3. Identity

The identity block establishes verifiable existence.

3.1 Structure

{
  "identity": {
    "name": "string, REQUIRED",
    "location": {
      "address": "string, REQUIRED",
      "coordinates": "[lat, lng], REQUIRED"
    },
    "domain": "string, RECOMMENDED",
    "did": "string, OPTIONAL"
  }
}

{
  "identity": {
    "name": "The Griffin Inn",
    "location": {
      "address": "Beacon Vale, Beaconshire LD3 0UB",
      "coordinates": [51.9634, -3.3842]
    },
    "domain": "griffininn.co.uk",
    "did": "did:web:griffininn.co.uk"
  }
}

3.2 Requirements

3.3 Decentralized Identifiers

Bookable uses DIDs for cryptographic identity. A DID proves the entity controls its Bookable record.

The did:web method ties identity to domain ownership. For higher trust requirements, other DID methods (did:ion, did:ethr) provide verification independent of DNS.

4. Evidence

The evidence block provides proof for claims, enabling defensible recommendations.

4.1 Structure

{
  "evidence": {
    "claimKey": {
      "claim": "string, REQUIRED",
      "value": "any, OPTIONAL",
      "confidence": "number 0-1, REQUIRED",
      "convergence": "string, REQUIRED",
      "sources": [ ],
      "lastVerified": "ISO-8601, RECOMMENDED"
    }
  }
}

4.2 Source Structure

{
  "sources": [
    {
      "type": "string, REQUIRED",
      "sourceRef": "string or array, REQUIRED",
      "method": "string, REQUIRED",
      "capturedAt": "ISO-8601, REQUIRED",
      "capturedBy": "string, RECOMMENDED",
      "verification": {
        "status": "string, REQUIRED",
        "verifiedBy": "string, OPTIONAL",
        "verifiedAt": "ISO-8601, OPTIONAL"
      }
    }
  ]
}

4.3 Source Types

Source types identify who provided the evidence:

4.4 Verification Status

4.5 Convergence Values

4.6 Verifiable Credentials

Claims MAY be elevated to Verifiable Credentials—cryptographically signed attestations from trusted issuers.

{
  "credentials": [
    {
      "@context": ["https://www.w3.org/2018/credentials/v1"],
      "type": ["VerifiableCredential", "AccessibilityCredential"],
      "issuer": "did:web:visitbeaconshire.gov.uk",
      "issuanceDate": "2024-03-15T00:00:00Z",
      "credentialSubject": {
        "id": "did:web:griffininn.co.uk"
      },
      "proof": { }
    }
  ]
}

Issuer Trust Levels:

5. Fit

The fit block declares explicit intent alignment—what the entity is good for, and what it is not.

5.1 Structure

{
  "fit": {
    "strong": [
      {
        "intent": "string, REQUIRED",
        "confidence": "number 0-1, REQUIRED",
        "signals": ["string"]
      }
    ],
    "weak": [
      {
        "intent": "string, REQUIRED",
        "reason": "string, REQUIRED"
      }
    ]
  }
}

5.2 Requirements

• fit.strong lists intents the entity is well-suited for
• fit.weak lists intents the entity is poorly-suited for
• Both arrays MAY be empty but SHOULD NOT be omitted

5.3 Weak Fit

Absence of weak fit declarations SHOULD NOT be interpreted as universal suitability.

6. Actions

The actions block declares what operations an agent can perform.

6.1 Structure

{
  "actions": {
    "capabilities": ["string"],
    "endpoint": "string, REQUIRED",
    "protocol": "string, REQUIRED",
    "authentication": {
      "type": "string",
      "flows": ["string"]
    }
  }
}

6.2 Base Capabilities

Domain extensions MAY define additional capabilities.

6.3 Protocol

Actions use JSON-RPC, the same transport as MCP.

7. Presentation

The presentation block defines UI components for human-in-the-loop confirmation.

7.1 Purpose

AI agents choose. Humans confirm. The presentation block enables rich UI rendering for that confirmation step.

7.2 Structure

{
  "presentation": {
    "a2uiVersion": "string",
    "components": {
      "componentId": {
        "type": "string, REQUIRED",
        "template": { }
      }
    },
    "layouts": {
      "layoutName": ["componentId"]
    }
  }
}

7.3 Component Types

7.4 Layouts

7.5 Progressive Enhancement

Agents without A2UI support SHOULD fall back to structured text derived from identity, evidence, and fit. The presentation block is OPTIONAL.

8. Answers

The answers block provides quotable, evidence-linked explanations for common agent questions.

8.1 Purpose

Agents need to explain recommendations, not just make them. The answers block provides canonical responses tied to evidence.

8.2 Structure

{
  "answers": [
    {
      "question": "string, REQUIRED",
      "answer": "string, REQUIRED",
      "confidence": "number 0-1, REQUIRED",
      "basedOn": ["string"],
      "citations": [ ],
      "lastVerified": "ISO-8601"
    }
  ]
}

8.3 Citation Structure

{
  "citations": [
    {
      "type": "string",
      "source": "string",
      "venuePath": "string"
    }
  ]
}

The venuePath field references the evidence block (e.g., evidence.dogFriendly, fit.strong[0]).

8.4 Regenerability Requirement

Agents MUST NOT trust answers that contradict underlying evidence.

9. Discovery

9.1 Well-Known Endpoint

Bookable-conformant records SHOULD be published at:

https://{domain}/.well-known/agent.json

9.2 DCAT Integration

Bookable supports DCAT for catalog and registry integration:

{
  "meta": {
    "catalogRef": "https://visitbeaconshire.gov.uk/catalog/venues",
    "datasetId": "felin-fach-griffin",
    "lastUpdated": "2024-10-20T00:00:00Z"
  }
}

This enables authorities to maintain catalogs of Bookables for discovery.

10. Extensions

Bookable is a base pattern. Domain-specific extensions add vocabulary:

10.1 Extension Declaration

{
  "bookable": {
    "type": "bookable:hotel",
    "extends": "bookable:bookable"
  }
}

10.2 Type Hierarchy

Bookable (base)
└── Venue (hospitality)
    ├── Accommodation (Hotel, BnB, Hostel)
    ├── Eat (Restaurant, Cafe, Bar)
    ├── Experience (Museum, Tour, Activity)
    └── Service (Spa, Salon)

Note: Stay defines the booking lifecycle, not a venue type.

11. Conformant Agent Behaviour

11.1 Fit Handling

Agents MUST NOT book when fit.weak matches user intent without disclosing the weak fit signal.

11.2 Evidence Staleness

Agents SHOULD warn users when lastVerified exceeds 90 days for material claims.

11.3 High-Consequence Claims

For safety-critical claims, agents MUST NOT assert claims at confidence < 0.8 without explicit caveat.

11.4 Conflict Handling

When convergence = conflicting, agents SHOULD:

• Disclose uncertainty to users
• Present the conflict rather than choosing silently
• Avoid strong assertions

12. Security Considerations

12.1 Trust Model

Bookable assumes good-faith actors but does not enforce behaviour. Evidence provenance enables post-hoc audit of recommendation decisions.

12.2 Integrity

Records SHOULD be served over HTTPS. Records with identity.did provide cryptographic verification of issuer.

12.3 Multiple Records

Multiple Bookable records MAY exist for the same entity, issued by different parties. Records MAY disagree—this is expected, not a defect.

Agents resolve conflicts via evidence weighting, not protocol authority.

Related Specifications

• Venue Spec — Hospitality extension
• Stay Spec — Booking lifecycle
• Folio Spec — Financial records
• Curator Spec — Authority curation