Creating Your Rulebook¶

Your rulebook is the definitive, human-readable, technical, and governance specification for your EAAs. It ensures that relying parties understand exactly what your credentials contain, how they're issued, and how to verify them.

Understanding Key Terminology

Rulebook: Human-readable specification covering technical requirements and governance for a credential type (this document)
Schema metadata: Machine-consumable entry in the catalog of attestations that references the rulebook, technical schemas, and trust list for authorized issuers
Catalog of attestations: Registry where you can look up what attestations are issued in the ecosystem
Trust list: List of authorized issuers and their certificates for a given credential type

Rulebook Components¶

A complete rulebook includes:

1. Purpose of the Credential¶

What to include:

Clear description of what the credential attests to
Intended use cases and scenarios
Users who should receive this credential
Benefits for users and relying parties

Example:

Purpose: This credential attests that the holder is a certified 
professional engineer licensed to practice in Germany. It enables 
the holder to prove their professional qualifications to employers, 
clients, and regulatory bodies without sharing unnecessary personal 
information.

2. Applicable Regulations¶

What to include:

Specific laws, regulations, or statutes that govern this credential
Industry-specific requirements
Sector regulations that influence issuance or use
Required trust levels

What NOT to include:

Generic laws that apply to all digital services (GDPR, NIS2, baseline eIDAS requirements)
These provide no additional value and clutter the rulebook

Example:

Applicable Regulations:
- Engineers Act (Ingenieurgesetz) § 12-15
- Professional Chambers Act § 8
- EU Professional Qualifications Directive 2005/36/EC
- End-to-end assurance target: High

3. Supported Credential Formats¶

Choose based on your use case:

SD-JWT VC (JSON-based)

Ideal for: Online verification scenarios, web and mobile apps
Benefits: Developer-friendly, widely supported, flexible
Use when: Most verification will happen remotely via web/app

ISO mDoc (ISO/IEC 18013-5)

Ideal for: Proximity scenarios (NFC, Bluetooth)
Benefits: Optimized for mobile, used for mobile driver's licenses
Use when: Physical/in-person verification is primary use case

Both formats

Consider supporting both if your use case spans online and proximity scenarios
Adds complexity but maximizes interoperability

Document in rulebook:

Supported Formats:
- Primary: SD-JWT VC
- Secondary: ISO mDoc (planned for Q3 2026)

4. Semantic Structure¶

Define all attributes that may appear in your credential.

What to include in your rulebook:

Your rulebook should document all credential attributes and their semantic meaning.

Your credential-specific attributes:

For each attribute, specify:

Attribute name (aligned with standards where possible)
Data type (string, number, date, boolean, image, etc.)
Whether mandatory or optional
Description and purpose
Format/encoding (if applicable)
Acceptable values (if constrained)

Design principles:

Use existing standards (ISO, W3C, etc.) where available
Align terminology with regulations
Minimize data collection (data minimization)
Harmonize with other EAA Providers of similar credentials
Enable selective disclosure (users should be able to share subsets)

Example:

{
  "credential_type": "professional_engineer_license",
  "attributes": {
    "license_number": {
      "type": "string",
      "required": true,
      "description": "Unique license identifier",
      "format": "DE-ENG-[0-9]{8}"
    },
    "given_name": {
      "type": "string",
      "required": true,
      "description": "First name(s) of license holder"
    },
    "family_name": {
      "type": "string",
      "required": true,
      "description": "Surname of license holder"
    },
    "date_of_birth": {
      "type": "date",
      "required": true,
      "description": "Birth date (YYYY-MM-DD)"
    },
    "specializations": {
      "type": "array",
      "required": false,
      "description": "Engineering specializations",
      "values": ["civil", "mechanical", "electrical", "software", "chemical"]
    },
    "issue_date": {
      "type": "date",
      "required": true,
      "description": "Date license was issued"
    },
    "expiry_date": {
      "type": "date",
      "required": true,
      "description": "License expiration date"
    },
    "issuing_chamber": {
      "type": "string",
      "required": true,
      "description": "Name of issuing professional chamber"
    }
  }
}

Be aware that when the updates are made to the attributes in the rulebook, you shall also need to update the credential schema and update the schema metadata entry in the catalog of attestations.

When you later create the schema metadata entry for the catalog of attestations, you will include machine-readable references to:

id - Unique identifier for this credential type
version - Version of the credential schema
rulebookURI - URL where this rulebook is published
supportedFormats - List of supported credential formats
schemaURIs - Links to technical schema definitions
trustedAuthorities - Trust anchors for signature verification
attestationLoS - Level of Assurance (eIDAS: Low, Substantial, High)
bindingType - How credential is bound to user (wallet/claim/biometric)

5. Trust & Governance Model¶

This section defines the core security design of your EAA. It's the most important part of your rulebook.

i. Validity Period¶

Balance security risk with user convenience.

Considerations:

Longer validity = attestation may be revoked before it expires, but better UX
Shorter validity = reduced risk, but more frequent renewal burden
Match underlying evidence validity where possible
Enable credential updates (you must store underlying data)
Best practice: Automate update processes

Guidance:

Treat EAAs as strong digital representations of the original credential
For long-term storage needs, ensure long-term validation capability like available status lists
Consider the nature of the attributes (how often do they change that would require a reissuance?)

Your rulebook must specify:

Default validity period for the credential type
Rationale for the chosen period based on attribute volatility, regulatory requirements, and user needs
Whether validity can be extended through refresh mechanisms (see below)

Example:

Validity Period: 24 months
Rationale: Professional licenses in our jurisdiction are valid for
2 years. Credential validity matches license validity.

Refresh: Supported via automated renewal process. Holders can refresh
credentials starting 30 days before expiration without re-identification
if their license remains valid. Users notified via wallet notification.

ii. User Identification¶

How you identify the person requesting the credential.

Options:

Not required - For low-security, non-personal credentials (e.g., event tickets)
High-assurance - Using PID or equivalent eIDAS Article 24 process
Reuse of prior identification - From account creation, onboarding with 2FA
Sector-specific methods - Industry-standard identification processes

Document:

The method used
How this identification contributes to the overall E2E assurance target
When identification occurs (at issuance, renewal, etc.)

Example:

User Identification: High-assurance via national PID
Process: Users must present their national Person Identification 
Data (PID) at initial license registration. Subsequent renewals 
use authenticated account access with 2FA.
Trust Level: High (eIDAS)

iii. Attribute Verification¶

How you ensure attributes are accurate and trustworthy.

Specify:

Whether you are the appropriate source for these data attributes
If not, where data originates and how you verify or trust the source.
Verification methods and evidence sources
Trust level of the verification process
Date of verification (especially if reusing prior verification)

Example:

Attribute Verification:
- Source: Chamber Registry Database
- Verification: Cross-reference with official examination records 
  and professional training certificates
- Process: Automated check against registry, manual review for 
  discrepancies
- Trust Level: High
- Frequency: Attributes verified at issuance and each renewal

iv. EAA Provider Requirements¶

Define what it takes to be a legitimate EAA Provider for this credential type.

Document:

EAA Provider status (authority, chamber membership, license, accreditation)
Registration requirements
Oversight or audit mechanisms

Example:

EAA Provider Requirements:
- Status: Accredited Professional Engineering Chamber recognized 
  under the Engineers Act
- Trust Anchor: German Professional Chambers Trust List, maintained 
  by Federal Ministry
- Registration: Chamber must be registered with State authority and 
  appear on official chambers registry
- Audit: Annual review by State oversight body

v. Credential Signature¶

EAAs must be electronically signed.

Requirements:

Use certificates linked to your trust anchor
Use signature containers appropriate to the credential format:
Follow BSI/ENISA recommendations
If long-term validity needed, provide long-term storage instructions

Example:

Signature:
- Type: Qualified Electronic Seal (QSeal)
- Format: JOSE/JWS for SD-JWT VC
- Certificate: Chamber QSeal certificate issued by qualified TSP
- Algorithm: RSA-PSS with SHA-256
- Long-term validation: Provide verifier guidance for long-term validation needs (e.g., key/cert rollover, archival of status information) when credentials must remain verifiable for many years.

vi. Revocation¶

Whether and how credentials can be revoked before their natural expiry.

When revocation is necessary:

Attributes may change (license suspended, privileges revoked)
Credential misuse poses significant risk
Regulatory requirements mandate revocation capability

When revocation may NOT be needed:

Very short-lived credentials (hours or days)
Low-risk credentials with minimal misuse potential
No mechanism for attributes to become invalid before expiry

Revocation mechanisms:

The revocation mechanism you use is related to your credential format. If you are issuing SD-JWTs, you are required to use a Token Status List. When using mDocs, you should use CRLs.

Your rulebook must specify:

Whether revocation is supported
Which revocation mechanism(s) are used
Expected maximum latency between revocation event and status update (for example, "within 4 hours")
Who can request revocation (holder, issuer, third party with appropriate authority)
Trigger events that require revocation
How revocation is communicated to affected parties

Revocation best practices:

High-trust EAAs should support revocation within 24 hours
Use status lists for privacy (no tracking of credential usage)
Avoid OCSP-style lookups that track when/where credentials are used
Provide user notification of revocations

Example:

Revocation:
- Supported: Yes
- Method: Privacy-preserving status list (Status List 2021)
- Timeline: Revocation effective within 4 hours
- Trigger events:
  - License suspension or revocation by regulatory authority
  - Holder request (lost device, security concern)
  - Credential issued in error
  - Security incident affecting credential integrity
- Who can request: Holder (via self-service portal), issuing chamber
  (via back-office system), regulatory authority (via official channel)
- User Notification: Email and wallet notification within 1 hour
- Relying Party requirement: Must check status list before accepting credential

vii. Anti-Tracking Measures¶

Prevent correlation of credential usage across relying parties.

Techniques:

Data minimization by default (issue only what is needed; support selective disclosure where the format allows it)
Avoid stable, globally unique identifiers that allow cross-RP correlation (only include them when legally/operationally required)
Prefer privacy-preserving status checking (avoid per-credential, per-presentation online callbacks that reveal where/when a credential is used)
If you support issuing multiple credential instances, document the operational trade-offs clearly (revocation, renewal, user UX, and relying party expectations)

Example:

Anti-Tracking:
- Selective disclosure: Enabled (SD-JWT VC) with clear relying party guidance on requesting only necessary claims
- Identifier policy: No globally unique holder identifier included unless required.
- Status privacy: Status checking uses a privacy-preserving mechanism and does not reveal presentation events
- Relying party policy: Requests must be minimized and proportional to the use case

6. Registration in the Catalog of Attestations¶

Once you have created your rulebook, you can register your credential type in the catalog of attestations by creating a schema metadata entry.

What is schema metadata?

Schema metadata is a machine-consumable entry in the catalog of attestations that includes:

Reference to your published rulebook (human-readable)
Links to technical schema definitions (JSON Schema, CDDL, etc.)
Reference to the trust list containing authorized issuers for this credential type
Machine-readable summary of key properties

Benefits of registration:

Enables discovery of your credential type in the ecosystem
Provides machine-readable information for wallets and relying parties
Links verification methods, signatures, and revocation rules
Allows relying parties to understand and selectively accept specific attributes
Facilitates trust establishment through trust list references

Note: The trust list referenced in the schema metadata contains the authorized EAA Providers (issuers) and their certificates. This is separate from the catalog of attestations, which is a registry of credential types.

Rulebook Documentation Format¶

Your rulebook should be:

Machine-readable (JSON schema or similar)
Human-readable (clear documentation)
Publicly accessible (published at stable URI)
Versioned (clear version control)
Maintained (updated as requirements evolve)