Skip to content

Conversation

@vrnvrn
Copy link

@vrnvrn vrnvrn commented Dec 22, 2025

Summary

This PR proposes documentation-only clarifications to ARKIV_STANDARD.md based on production experience from p2pmentor (an Arkiv application). The goal is to prevent common implementation mistakes by making update semantics and reference handling more explicit.

Changes

  1. Add an Anti-patterns section under Base Entity Types
  2. Add Entity Mutation Semantics (explicitly clarifies replacement semantics for attributes and payload; documents attribute removal by omission; clarifies $lastUpdatedAt)
  3. Strengthen guidance on server-side reference resolution
  4. Clarify arrays-as-strings as tokens-only and point to JSON payloads for complex structures
  5. Add typeVersion compatibility expectations
  6. Minor spec polish: TOC updates and valid JSON examples

Notes

  • Documentation only (non-breaking)
  • No Change Log or “Last updated” metadata edits included; leaving spec metadata decisions to maintainers

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant