VRS v1.0

Overview

The Veydrin Rating Standard (VRS) defines a decentralized system for collecting, storing, and displaying software ratings and usage counters. Every record is a cryptographically signed JSON document committed to a public git repository. No centralized service controls the data. No platform gatekeeper mediates trust.

All VRS documents MUST be serialized as JSON (RFC 8259) and encoded as UTF-8. The RECOMMENDED file extension is .vrs.json.

VRS defines two record types:

• Counter — an anonymous acknowledgment of usage. No requirements to submit. One per installation per application.
• Rating — a quality assessment (1–5 stars with optional comment). Gated by proof of contribution: the user MUST have submitted at least one valid VODS export before a rating is accepted. One per installation per application.

VRS is not a child of VODS. It is a sibling protocol that references VODS for contribution gating. Both protocols share the same design philosophy: offline-capable, privacy-respecting, publicly verifiable, and free from platform dependency.

Scope

VRS applies to all software published by The Veydrin Order. Any third-party organization or individual MAY adopt VRS by implementing the conformance requirements in §10.

Out of scope

VRS does not define: the HTTP API for record submission (transport is implementation-defined), server provisioning or deployment, migration from existing rating systems, or user interface design beyond the requirements in §9. A VODS export is a structured data document conforming to the Veydrin Open Data Standard; the export_id is its unique UUID v4 identifier assigned at creation time.

Known implementations

Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC 2119] [RFC 8174] when, and only when, they appear in ALL CAPITALS, as shown here.

Record types

Counter record

A counter record is an anonymous signal that an installation of the software exists. It carries no assessment and requires no prior contribution. Any user MAY submit a counter record at any time by tapping a single button in the application.

Rating record

A rating record is a quality assessment of the software. It carries a star value (1–5) and an optional free-text comment. A rating record MUST include a contribution_proof that demonstrates genuine usage. VRS defines two proof types:

• vods:{export_id} — References the export_id of a previously accepted VODS export. The server MUST verify the export exists in the dataset. Used by applications that contribute data publicly (e.g., Apiara submitting OHDS data to Ojarim).
• counter:{record_id} — References the record_id of a previously accepted VRS counter record from the same public_key. The server MUST verify the counter exists and the public keys match. Used by applications whose data is private and never contributed (e.g., financial or health software).

The proof type prefix (vods: or counter:) MUST be present. Each application declares which proof type it requires. Applications that contribute data publicly SHOULD require vods: proofs for the stronger guarantee.

Examples

Counter record

{
  "vrs_version":        "1.0",
  "record_type":        "counter",
  "record_id":          "b7e4f2a1-9c83-4d1f-a562-3e8b01cc7f94",
  "source_app":         "org.veydrin.apiara",
  "source_app_version": "2.0.0",
  "timestamp":          "2026-03-31T08:14:00-05:00",
  "public_key":         "MCowBQYDK2VwAyEA...",
  "signature":          "dGhpcyBpcyBhIHNp..."
}

Rating record

{
  "vrs_version":        "1.0",
  "record_type":        "rating",
  "record_id":          "a1f8c3d2-7b04-4e9a-b331-6f2a08dd2c93",
  "source_app":         "org.veydrin.apiara",
  "source_app_version": "2.0.0",
  "timestamp":          "2026-03-31T09:22:00-05:00",
  "stars":              5,
  "comment":            "Best beekeeping app I have used. The varroa tracking alone is worth it.",
  "contribution_proof": "a3f8c2e1-04b7-4d9e-b221-7f3a09cc1d82",
  "public_key":         "MCowBQYDK2VwAyEA...",
  "signature":          "c2lnbmF0dXJlIGRh..."
}

Rating record (no comment)

{
  "vrs_version":        "1.0",
  "record_type":        "rating",
  "record_id":          "d4e2b1a3-8f07-4c5d-9912-1a3b04ee5f76",
  "source_app":         "org.veydrin.apiara",
  "source_app_version": "2.0.0",
  "timestamp":          "2026-03-31T11:45:00-05:00",
  "stars":              4,
  "contribution_proof": "f7c1d3e4-2a08-4b6f-8e33-9d5c02bb8a41",
  "public_key":         "MCowBQYDK2VwAyEA...",
  "signature":          "YW5vdGhlciBzaWdu..."
}

Aggregate with zero ratings

{
  "source_app":      "org.veydrin.apiara",
  "counter_total":   42,
  "rating_count":    0,
  "rating_average":  null,
  "rating_distribution": {
    "1": 0, "2": 0, "3": 0, "4": 0, "5": 0
  },
  "last_updated":    "2026-03-31T10:00:00Z"
}

Edge cases

Cryptographic signing

Keypair generation

On first launch, the application MUST generate an Ed25519 keypair and store it in secure local storage. The private key MUST NOT leave the device. The public key is embedded in every VRS record submitted by that installation.

If the application is uninstalled and reinstalled, a new keypair is generated. The previous keypair is lost. This is by design — it provides natural rate-limiting without centralized enforcement.

Canonical form

Before signing, the record MUST be serialized to its canonical form: all fields except signature, serialized as a JSON object with keys sorted lexicographically, no whitespace, UTF-8 encoded. The signature is computed over this canonical byte string.

// Canonical form for signing (no whitespace, keys sorted, no signature field):
{"contribution_proof":"a3f8...","public_key":"MCow...","record_id":"a1f8...","record_type":"rating","source_app":"org.veydrin.apiara","source_app_version":"2.0.0","stars":5,"timestamp":"2026-03-31T09:22:00-05:00","vrs_version":"1.0"}

Signature algorithm

Ed25519 as defined in RFC 8032. Implementations MUST use Ed25519 (pure mode, not Ed25519ctx or Ed25519ph). The signature is Base64-encoded (standard alphabet, with padding) and placed in the signature field.

Test vectors

The following test vectors use a real Ed25519 keypair. Implementations MUST be able to verify these signatures. All three records share the same keypair.

Public key (Base64): 27uBCPa4dYsnFMSQVTVwCbKo28or/2AQ8XFDJp8ro3g=

Vector 1 — Counter record

// Canonical form (input to sign):
{"public_key":"27uBCPa4dYsnFMSQVTVwCbKo28or/2AQ8XFDJp8ro3g=","record_id":"b7e4f2a1-9c83-4d1f-a562-3e8b01cc7f94","record_type":"counter","source_app":"org.veydrin.apiara","source_app_version":"2.0.0","timestamp":"2026-03-31T08:14:00-05:00","vrs_version":"1.0"}

// Signature (Base64):
9HBf+Dl6Zzu35Veunyqik25jxxv/spRfZRJIvbuo+C7olErB+D4+vN9znim8D1i+vXmgLbNQfds0+FAHpzk7DA==

Vector 2 — Rating record (with comment)

// Canonical form:
{"comment":"Excellent varroa tracking.","contribution_proof":"a3f8c2e1-04b7-4d9e-b221-7f3a09cc1d82","public_key":"27uBCPa4dYsnFMSQVTVwCbKo28or/2AQ8XFDJp8ro3g=","record_id":"a1f8c3d2-7b04-4e9a-b331-6f2a08dd2c93","record_type":"rating","source_app":"org.veydrin.apiara","source_app_version":"2.0.0","stars":5,"timestamp":"2026-03-31T09:22:00-05:00","vrs_version":"1.0"}

// Signature:
ZsauOCF9UjGXPZjWqMg2Vjva8sQuJhmZta+HQ8VQHhzPpFrNn7S68s61fWmIPT0mQRXsBLAY469h7PdrFHDyBw==

Vector 3 — Rating record (no comment)

// Canonical form (note: comment field absent, not null):
{"contribution_proof":"f7c1d3e4-2a08-4b6f-8e33-9d5c02bb8a41","public_key":"27uBCPa4dYsnFMSQVTVwCbKo28or/2AQ8XFDJp8ro3g=","record_id":"d4e2b1a3-8f07-4c5d-9912-1a3b04ee5f76","record_type":"rating","source_app":"org.veydrin.apiara","source_app_version":"2.0.0","stars":4,"timestamp":"2026-03-31T11:45:00-05:00","vrs_version":"1.0"}

// Signature:
MlXvB2rZLrqGHGsUR2OKEBJ5jN9hSC4/nqy1mNIMzj2gsM6g22beK82JZPR4Twjze7vj5uMjzkeNk4YOAo6HDQ==

Repository structure

VRS records are stored in a public git repository. Each application has its own directory. Records are stored as individual JSON files named by their record_id.

ratings/
  org.veydrin.apiara/
    counters/
      b7e4f2a1-9c83-4d1f-a562-3e8b01cc7f94.json
      ...
    ratings/
      a1f8c3d2-7b04-4e9a-b331-6f2a08dd2c93.json
      ...
  org.ninthstar.covara/
    counters/
      ...
    ratings/
      ...

The repository MUST be publicly readable. Write access is controlled by the repository owner (the organization publishing the software). Records are committed by the server after validation.

Aggregate file

Supporter number

When the server commits a counter or rating record, it SHOULD assign a sequential supporter number to the record. This number represents the order in which the record was accepted (e.g., the 247th counter record receives supporter number 247). The supporter number is returned in the server response and MAY be displayed in the application as a personal identifier (e.g., "#247").

The supporter number is NOT stored in the signed record itself — it is assigned server-side after validation. It is stored in the aggregate.json file and optionally in a lightweight index file for lookup.

Aggregate file

Each application directory SHOULD contain an aggregate.json file that is regenerated after each new record. This file provides a pre-computed summary for efficient in-app display.

{
  "source_app":      "org.veydrin.apiara",
  "counter_total":   1847,
  "rating_count":    312,
  "rating_average":  4.7,
  "rating_distribution": {
    "1": 3,
    "2": 5,
    "3": 18,
    "4": 72,
    "5": 214
  },
  "last_updated":    "2026-03-31T10:00:00Z"
}

Scalability

For applications with more than 100,000 records, repository operators SHOULD consider:

• Shallow clones for consumers that only need the aggregate file.
• Periodic repository packing (git gc --aggressive) to reduce on-disk size.
• Archival strategies: moving records older than a defined threshold to an archive/ branch while preserving the aggregate on the main branch.
• Splitting by year: counters/2026/, counters/2027/ to limit directory size.

The aggregate file MUST always reflect the full count regardless of archival — it is the single source of truth for display purposes.

Verification and deduplication

Server-side validation

Before committing a record to the repository, the server MUST perform all of the following checks:

1. The vrs_version field is a supported version.
2. The record_type is "counter" or "rating".
3. All required fields for the record type are present and correctly typed.
4. The record_id is a valid UUID v4 and does not already exist in the repository.
5. The signature is valid against the public_key using the canonical form (§5).
6. The stars value (if rating) is an integer from 1 to 5 inclusive.
7. The comment (if present) does not exceed 500 UTF-8 characters.
8. Deduplication: No existing record in the repository shares the same public_key and source_app combination for the same record_type.
9. Contribution proof (ratings only): The contribution_proof value matches the export_id of an accepted VODS export in the associated dataset.

If any check fails, the server MUST reject the record and MUST NOT commit it.

Client-side verification

Applications displaying VRS data MAY verify individual records by checking the Ed25519 signature against the embedded public key. Applications that fetch only the aggregate.json file are trusting the repository owner's computation — this is acceptable because the raw data is always publicly available for independent verification.

Anti-gaming measures

VRS does not claim to be immune to manipulation. It claims to make manipulation expensive, visible, and auditable.

Primary defense: proof of usage

Rating records require a valid contribution_proof. For data-contributing apps (vods: proof), an attacker must generate a valid VODS export that passes schema validation — producing realistic beekeeping or cultivation data is real effort for zero payoff. For private apps (counter: proof), the attacker must have submitted a counter first, proving an actual installation exists. The vods: gate is stronger; the counter: gate is appropriate for applications whose data cannot be shared publicly.

Secondary defense: keypair binding

Each installation generates exactly one Ed25519 keypair. Submitting multiple ratings for the same application requires multiple installations, each with its own keypair, each with its own valid VODS contribution. This is not impossible, but it is slow and effortful.

Tertiary defense: public auditability

The entire ratings repository is public. Anyone can:

• Clone the repository and recompute the aggregate independently.
• Analyze submission patterns (timestamps, public key clustering, contribution proof reuse).
• Flag suspicious records for review by the repository owner.

A flood of ratings from keys with minimal or suspiciously similar contributions is visible to anyone who looks. Transparency is the deterrent.

Server-side rate limiting

Servers SHOULD implement rate limiting on new record submissions. A RECOMMENDED baseline: no more than 10 new records per source IP per hour. This prevents automated flooding while permitting normal usage patterns.

In-app display

Conforming applications MUST display both the counter total and the rating aggregate within the application. The display SHOULD include:

• Counter total (number of installations that have tapped the counter).
• Average star rating (one decimal place).
• Number of ratings.
• A prompt to submit a counter (always available) and a rating (available after contributing data).

Applications SHOULD fetch the aggregate.json file from the repository and cache it locally. The cache SHOULD be refreshed no more than once per 24 hours to avoid unnecessary load on the repository host.

Conformance

Conformance targets

VRS defines four conformance targets:

• VRS Client — an application that generates keypairs, constructs and signs records, and displays aggregates (R1–R7).
• VRS Server — a service that validates records and commits them to the repository (R8 plus §7 requirements).
• VRS Verifier — any system that checks Ed25519 signatures on VRS records (§5 requirements).
• VRS Consumer — any system that reads and displays aggregate data (§9 display rules). Consumers MUST ignore unknown fields. Consumers SHOULD verify signatures when processing individual records.

Conformance profiles

VRS Counter-Only Profile: A client that implements only counter functionality. MUST satisfy R1, R2, R3, R4 (counter only), R6 (counter display), R7. Rating rules do not apply. This profile lowers the adoption barrier for applications that do not use VODS.

VRS Full Profile: A client that implements both counter and rating functionality. MUST satisfy all rules R1–R8.

In addition to the rules below, all statements using MUST, MUST NOT, REQUIRED, SHALL, or SHALL NOT elsewhere in this specification are normative requirements on the applicable conformance target.

Rules

A conforming VRS implementation MUST satisfy all of the following rules:

• R1
  Keypair generation. The application MUST generate an Ed25519 keypair on first launch and store it in platform-appropriate secure storage. The private key MUST NOT be exported, transmitted, or backed up to any external service.
• R2
  Record format. All submitted records MUST conform to the field tables in §3. All required fields MUST be present. The vrs_version field MUST be set to the version this implementation targets.
• R3
  Canonical signing. The signature MUST be computed over the canonical JSON form defined in §5. Implementations MUST use Ed25519 pure mode (RFC 8032).
• R4
  One record per type per app. An installation MUST NOT submit more than one counter record and one rating record for the same source_app. The application SHOULD persist a local flag indicating whether each record type has been submitted.
• R5
  Proof of usage. A rating record MUST include a contribution_proof with a valid proof type prefix (vods: or counter:). The referenced record MUST exist and be valid. The application MUST NOT submit a rating until the proof prerequisite is met.
• R6
  In-app display. The application MUST display the counter total and rating aggregate somewhere accessible within the application UI.
• R7
  No coercion. The application MUST NOT require a rating to access any feature. The application MUST NOT prompt for a rating more than once per session. Counter and rating actions MUST be initiated by the user, never automatic.
• R8
  Server validation. The receiving server MUST validate all records per §7 before committing to the repository. Invalid records MUST be rejected.

Security and privacy considerations

Public key as pseudonym

The Ed25519 public key embedded in each record acts as a pseudonym. It does not reveal the user's identity, device, or location. However, if the same public key appears in both a counter and a rating for the same application, those records are linkable. This linkage is by design — it enables deduplication — but implementations SHOULD document it for users.

Contribution proof linkage

The contribution_proof field links a rating to a specific VODS export. In anonymous mode VODS exports, the export_id is a random UUID that does not reveal identity. In tracked mode, the export_id is still a UUID but may be correlated with a longitudinal pseudonym in the dataset. Users who submit ratings after tracked mode exports SHOULD be aware of this potential correlation.

Comment sanitization

Free-text comments MAY contain personal information inadvertently. Applications SHOULD warn users before submission: "Your comment will be publicly visible in the ratings repository. Do not include personal information." Server-side processing MAY reject comments that match common PII patterns (email addresses, phone numbers), but this is NOT REQUIRED.

Consent and data protection

Submission of a VRS record constitutes user-initiated disclosure. Applications MUST NOT submit records without explicit user action (tap or click). Applications SHOULD display what data will be submitted before the user confirms. Where GDPR or similar regulations apply, this user action constitutes consent; implementers MUST determine the appropriate legal basis for their jurisdiction.

VRS records are pseudonymous and contain no directly identifying information. Under GDPR Article 17 (right to erasure), whether a pseudonymous public key constitutes personal data depends on jurisdiction and context. If erasure is required, the record MAY be replaced with a tombstone record containing only record_id and a deletion notice, and the aggregate MUST be recomputed.

Threat model

Repository integrity

The git history of the ratings repository provides a tamper-evident log. Any modification to a committed record is visible in the commit history. Repository owners MUST NOT force-push or rewrite history on the ratings branch. Consumers of VRS data MAY verify repository integrity by checking that no force-pushes have occurred.

Replay attacks

Each record has a unique record_id (UUID v4). The server MUST reject duplicate record_id values. Additionally, the deduplication rule (one public_key per source_app per record_type) prevents replaying a record with a new UUID — the public key would already be present.

Key compromise

If a private key is compromised, the attacker can submit one counter and one rating (if they also possess a valid contribution proof). The blast radius is exactly two records. There is no mechanism for key revocation — the simplicity of VRS depends on not needing one. Two records is an acceptable maximum damage per compromised key.

Glossary

Normative references

• RFC 2119 — Key words for use in RFCs to Indicate Requirement Levels
• RFC 8174 — Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
• RFC 8032 — Edwards-Curve Digital Signature Algorithm (EdDSA) — Ed25519
• RFC 9562 — Universally Unique Identifiers (UUIDs) — UUID v4
• RFC 3339 — Date and Time on the Internet: Timestamps
• RFC 8259 — The JavaScript Object Notation (JSON) Data Interchange Format
• VODS v1.0 — Veydrin Open Data Standard — veydrin.codeberg.page/protocols/vods

Versioning policy

VRS follows Semantic Versioning 2.0.0. The version number appears in the vrs_version field of every record as "MAJOR.MINOR".

• PATCH — editorial corrections, clarifications. No data format changes. Records are unaffected.
• MINOR — new optional fields or record types. Existing records remain valid. Consumers MUST accept records from any MINOR version with the same MAJOR.
• MAJOR — breaking changes to required fields, signing algorithm, or record structure. Old records MAY not be valid under the new version.

Deprecation policy: features MAY be deprecated in a MINOR release. Deprecated features MUST NOT be removed earlier than the next MAJOR release.

Governance

VRS is maintained by The Veydrin Order. The specification is authored and reviewed by the project leads (see protocols repository AUTHORS). All design decisions are recorded as Codeberg issues or commit messages in the repository history.

Change process: Anyone may propose changes by opening an issue on the protocols repository. Proposals are reviewed by The Veydrin Order maintainers. Acceptance criteria: the change must improve interoperability, security, or adoption without breaking existing conforming implementations (unless a MAJOR version bump is warranted). Editorial corrections may be applied without an issue.

Errata: Errors discovered after publication may be corrected as inline fixes tagged with [Erratum YYYY-MM-DD] in the changelog. Errata do not change the version number. A list of active errata is maintained in the changelog section.

Code of conduct: Participants in VRS development are expected to engage respectfully and constructively. The Veydrin Order reserves the right to moderate interactions on its repositories.

All intellectual property is published under CC-BY-4.0 with a royalty-free patent commitment — no contributor may encumber VRS with patent claims.

Forward compatibility

When verifying signatures, the canonical form MUST include all fields present in the record (except signature), sorted lexicographically, regardless of whether the verifier recognizes them. This ensures that a VRS 1.0 verifier can verify records produced by VRS 1.1 that contain new fields.

Conforming consumers MUST ignore unknown fields when processing VRS records. Unknown fields MUST NOT cause validation failure.

Trademark

The names "VRS" and "Veydrin Rating Standard" are not trademarked. Implementers MAY use the phrases "conforms to VRS v1.0" or "VRS-compatible" without a trademark license, provided the implementation genuinely conforms to this specification.

Succession

If The Veydrin Order ceases to operate, stewardship of VRS transfers to the community via the CC-BY-4.0 license. Any party may fork and continue development. The specification and all associated schemas are permanently available in the public repository.

Changelog