Protocol Specification

AiHint Global Hint — Specification v0.1

The AiHint Global Hint is a JSON document that contains signed, verifiable metadata about a domain. It is placed at a well-known URL so that AI systems can discover and consume it without prior configuration.

File Location

An AiHint file MUST be served at:

https://<domain>/.well-known/aihint.json

For example:

https://example.com/.well-known/aihint.json

Requirements

• The file MUST be served over HTTPS.
• The file MUST have a Content-Type of application/json.
• The file SHOULD be accessible without authentication.
• The server SHOULD return appropriate cache headers (e.g., Cache-Control: max-age=86400).

Fields

The AiHint Global Hint document is a JSON object with the following fields:

Field	Type	Required	Description
version	string	Yes	AiHint specification version (currently "0.1")
type	string	Yes	Document type. MUST be "global"
target	string (URI)	Yes	The domain URL this hint describes
issuer	string (URI)	Yes	URL of the issuing authority that created this hint
score	number	Yes	Trust/reputation score, from 0.0 (no trust) to 1.0 (full trust)
method	string	Yes	Identifier for the scoring methodology used
issued_at	string (ISO 8601)	Yes	Timestamp when this hint was created
expires_at	string (ISO 8601)	Yes	Timestamp when this hint expires and should no longer be trusted
comment	string | null	No	Optional human-readable description or note
signature	string	Yes	Base64-encoded RSA signature of the document (see Signatures)
public_key_url	string (URI)	Yes	URL where the issuer's public key can be fetched for verification

Field Details

version

The specification version this document conforms to. Currently, the only valid value is "0.1".

"version": "0.1"

type

The document type. For the Global Hint, this MUST be "global".

"type": "global"

target

The full URL of the domain this hint describes. This MUST be a valid URI.

"target": "https://example.com"

issuer

The URL of the authority that created and signed this hint. This is the entity vouching for the trust score. The issuer's public key should be available at the URL specified in public_key_url.

"issuer": "https://trust.aihint.org"

score

A floating-point number between 0.0 and 1.0 (inclusive) representing the trust score assigned to the target domain.

Range	Interpretation
0.0–0.2	Very low trust / potentially harmful
0.2–0.4	Low trust / limited verification
0.4–0.6	Moderate trust / basic verification
0.6–0.8	Good trust / substantial verification
0.8–1.0	High trust / comprehensive verification

"score": 0.92

method

A string identifier for the scoring methodology used to calculate the trust score. This allows consumers to understand how the score was derived.

"method": "aihint-core-v1"

issued_at

An ISO 8601 datetime string indicating when this hint was created.

"issued_at": "2025-06-15T12:00:00Z"

expires_at

An ISO 8601 datetime string indicating when this hint expires. After this time, consumers SHOULD NOT trust this hint and SHOULD attempt to fetch a fresh copy.

"expires_at": "2026-06-15T12:00:00Z"

comment

An optional human-readable string providing context about the hint. May be null or omitted entirely.

"comment": "Verified domain with strong trust signals"

signature

A Base64-encoded RSA signature of the document. The signature covers all fields except the signature field itself. See Signature Algorithm for the full signing and verification process.

"signature": "Base64EncodedRSASignature..."

public_key_url

A URL where the issuer's RSA public key can be fetched in PEM format. Consumers use this key to verify the signature.

"public_key_url": "https://trust.aihint.org/pubkey.pem"

Complete Example

{
  "version": "0.1",
  "type": "global",
  "target": "https://example.com",
  "issuer": "https://trust.aihint.org",
  "score": 0.92,
  "method": "aihint-core-v1",
  "issued_at": "2025-06-15T12:00:00Z",
  "expires_at": "2026-06-15T12:00:00Z",
  "comment": "Verified domain with strong trust signals",
  "signature": "dGhpcyBpcyBhIHNhbXBsZSBzaWduYXR1cmU...",
  "public_key_url": "https://trust.aihint.org/pubkey.pem"
}

Validation

A valid AiHint document MUST:

1. Be valid JSON
2. Contain all required fields
3. Have type set to "global"
4. Have score between 0.0 and 1.0
5. Have valid ISO 8601 timestamps for issued_at and expires_at
6. Have valid URIs for target, issuer, and public_key_url
7. Have a non-empty signature string

A JSON Schema for automated validation is available in the Schema Reference.

Next Steps

• JSON Schema — Machine-readable validation schema
• Signature Algorithm — How signing and verification work
• Implementation Guide — Deploy AiHint on your domain