use schema.rtemis.org/a3/v1/schema.json by egenn · Pull Request #7 · rtemis-org/a3

egenn · 2026-03-31T12:20:45Z

No description provided.

gemini-code-assist

Code Review

This pull request implements mandatory envelope fields, $schema and a3_version, across the A3 format's R, Python, TypeScript, Julia, and Rust implementations. It includes a new JSON schema, updated specifications, and corresponding validation and serialization logic across all supported languages. Feedback recommends using package-level constants in R for better maintainability and utilizing .pop() in Python for more efficient dictionary manipulation when stripping envelope keys.

gemini-code-assist · 2026-03-31T12:23:16Z

+  .a3_schema_uri <- "https://schema.rtemis.org/a3/v1/schema.json"
+  .a3_version <- "1.0.0"


The schema URI and version strings are hardcoded here and also in the to_json method (lines 887-888). To improve maintainability and ensure consistency across the package, these should be defined as package-level constants (e.g., .A3_SCHEMA_URI and .A3_VERSION) at the top of the file or in a central configuration file.

gemini-code-assist · 2026-03-31T12:23:16Z

+            f"'a3_version' must be '{_A3_VERSION}', got '{version_val}'"
+        )
+    # Strip envelope keys before passing to the data model
+    data = {k: v for k, v in data.items() if k not in _ENVELOPE_KEYS}


Creating a new dictionary via a comprehension to strip envelope keys is functional but slightly less efficient than in-place modification, especially for larger objects. Since data is a fresh dictionary returned by json.loads, you can use .pop() to remove the keys in-place.

Suggested change

data = {k: v for k, v in data.items() if k not in _ENVELOPE_KEYS}

for key in _ENVELOPE_KEYS:

data.pop(key, None)

Copilot

Pull request overview

This PR standardizes the A3 “envelope” across languages by requiring $schema and a3_version on JSON input, emitting them on serialization, and adding a published JSON Schema at https://schema.rtemis.org/a3/v1/schema.json.

Changes:

Enforce $schema + a3_version validation across TypeScript, Python, R, Julia, and Rust implementations and update tests/examples accordingly.
Add a JSON Schema document (schema/a3.schema.json) and update the spec docs to describe the envelope fields.
Add a root Makefile to run tests/docs across the multi-language repo.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
typescript/tests/schemas.test.ts	Updates schema validation tests to include envelope fields.
typescript/tests/a3.test.ts	Updates A3 class tests to include envelope fields in some constructors/serialization checks.
typescript/src/schemas.ts	Adds exported envelope constants and requires `$schema`/`a3_version` in `A3InputSchema`.
typescript/src/a3.ts	Ensures serialized output includes envelope fields first.
specs/A3.md	Documents `$schema` and `a3_version`, updates implementation-note links, and adds `.a3.json` extension note.
specs/A3_Rust.md	Renames Rust spec title/wording.
schema/a3.schema.json	Introduces JSON Schema for A3 v1.
rust/src/validation.rs	Adds envelope field validation and propagates validated envelope fields into normalized output.
rust/src/types.rs	Adds `$schema`/`a3_version` fields to the Rust `A3` type and constants for expected values.
rust/src/lib.rs	Updates docs/tests and adds tests for missing/wrong envelope fields.
r/tests/testthat/test_A3.R	Updates JSON fixtures to include envelope fields.
r/R/a3.R	Emits envelope fields in `to_json()` and validates them in `A3from_json()`.
python/rtemis_a3/tests/test_api.py	Updates API tests for envelope requirements and adds missing-field tests.
python/rtemis_a3/src/rtemis/a3/api.py	Validates envelope fields in `a3_from_json()` and emits them in `a3_to_json()`.
Makefile	Adds multi-language test and docs targets.
julia/RtemisA3/test/runtests.jl	Updates tests for envelope requirements.
julia/RtemisA3/src/validate.jl	Validates envelope fields and allows them as recognized top-level keys.
julia/RtemisA3/src/io.jl	Emits envelope fields in dictionary serialization.
julia/RtemisA3/src/api.jl	Includes envelope fields in `create_a3()` raw dict.
examples/mapt.a3.json	Adds envelope fields to example A3 JSON.

Comments suppressed due to low confidence (1)

specs/A3.md:173

In the Stage 1 validation bullets, the ranges line says "overlaps merged", but earlier in this same spec (Ranges definition) and in all language implementations, overlapping ranges are rejected (not merged). This looks like a spec inconsistency and could mislead implementers; consider updating the bullet to match the actual behavior (reject overlaps).

- `$schema`: required string; must equal `"https://schema.rtemis.org/a3/v1/schema.json"`
- `a3_version`: required string; must equal `"1.0.0"`
- `sequence`: non-empty, `[A-Za-z*]+` (uppercased on parse), ≥ 2 characters
- Positions: positive integers, sorted, deduplicated
- Ranges: positive integers, `start < end`, sorted, overlaps merged
- Annotation entries: `{ index, type }` objects — bare arrays rejected

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-31T12:28:14Z

+  "type": "object",
+  "required": ["$schema", "a3_version", "sequence", "annotations", "metadata"],
+  "additionalProperties": false,


The JSON Schema currently marks annotations and metadata as required at the top level. This conflicts with the spec and implementations in this repo that default missing annotations/metadata on input (e.g., TypeScript A3InputSchema defaults both, and Python model defaults both). As a result, minimal JSON like { "$schema": ..., "a3_version": ..., "sequence": ... } is accepted by libraries but would be rejected by this schema. Consider making annotations and metadata optional here (and similarly relaxing nested requirements) so $schema validation matches what parsers accept.

Copilot · 2026-03-31T12:28:15Z

+    },
+    "annotations": {
+      "type": "object",
+      "required": ["site", "region", "ptm", "processing", "variant"],


Within annotations, the schema requires all five families (site, region, ptm, processing, variant). Repo implementations accept partial annotations objects and default missing families to empty (e.g., TS tests assert this behavior). To keep the JSON Schema aligned with accepted input, consider removing/relaxing this required list (or otherwise making the families optional with defaults).

Suggested change

"required": ["site", "region", "ptm", "processing", "variant"],

Copilot · 2026-03-31T12:28:15Z

  it("serialized JSON contains all annotation families", () => {
-    const a3 = new A3({ sequence: "MKTAY" });
+    const a3 = new A3({
+      $schema: "https://schema.rtemis.org/a3/v1/schema.json",


Now that $schema/a3_version are mandatory, several tests in this file still construct invalid inputs without the envelope (e.g., earlier new A3({ sequence: ... }) cases). Those tests will still throw, but for the wrong reason (missing envelope instead of the intended validation like "too short" or "out of bounds"), reducing coverage. Consider updating those invalid-input tests to include the correct envelope so they continue to exercise the specific validation being asserted.

Copilot · 2026-03-31T12:28:15Z

@@ -166,6 +172,8 @@ describe("A3.toJSON and JSON.stringify", () => {

  it("type field is always present on annotation entries", () => {


The schema URI and version are now duplicated as string literals in multiple places in this file. Since typescript/src/schemas.ts exports A3_SCHEMA_URI and A3_VERSION, consider importing and reusing those constants in tests to avoid future drift if the URI/version ever changes.

Copilot · 2026-03-31T12:28:16Z

+      $schema: "https://schema.rtemis.org/a3/v1/schema.json",
+      a3_version: "1.0.0",
+      sequence: "MKTAYIAKQR",


This test hardcodes the schema URI and version inline while the file already has MINIMAL_VALID (and schemas.ts exports A3_SCHEMA_URI/A3_VERSION). Consider reusing a shared constant/object here to reduce duplication and the chance of the URI/version drifting across tests.

Suggested change

$schema: "https://schema.rtemis.org/a3/v1/schema.json",

a3_version: "1.0.0",

sequence: "MKTAYIAKQR",

$schema: MINIMAL_VALID.$schema,

a3_version: MINIMAL_VALID.a3_version,

sequence: MINIMAL_VALID.sequence,

use schema.rtemis.org/a3/v1/schema.json

c526b9f

Copilot AI review requested due to automatic review settings March 31, 2026 12:20

cargo fmt

45933a5

gemini-code-assist Bot reviewed Mar 31, 2026

View reviewed changes

Copilot started reviewing on behalf of egenn March 31, 2026 12:23 View session

biome

7ebb222

Copilot AI reviewed Mar 31, 2026

View reviewed changes

egenn added 10 commits March 31, 2026 06:14

refactor: update toJSON method to return A3Data with schema fields last

a20046f

fix: update test script to include type checking before running vitest

5035893

fix: optimize envelope key removal in a3_from_json function

97799f9

fix: centralize schema URI and version constants in A3 implementation

289018a

fix: remove unnecessary required fields from A3 schema

e627d02

fix: replace hardcoded schema URI and version with constants in tests

f94fc76

fix: update A3 specification to clarify handling of overlapping ranges

e571234

fix: replace hardcoded schema URI and version with constants in A3 tests

8daf5b0

fix: format error expectation for A3ValidationError in constructor tests

8943174

fix: update test script to include pnpm check before running vitest

2c6ac08

egenn merged commit 28cf892 into main Mar 31, 2026
7 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

use schema.rtemis.org/a3/v1/schema.json#7

use schema.rtemis.org/a3/v1/schema.json#7
egenn merged 13 commits into
mainfrom
schema

egenn commented Mar 31, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Mar 31, 2026

Uh oh!

gemini-code-assist Bot Mar 31, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 31, 2026

Uh oh!

Copilot AI Mar 31, 2026

Uh oh!

Copilot AI Mar 31, 2026

Uh oh!

Copilot AI Mar 31, 2026

Uh oh!

Copilot AI Mar 31, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		.a3_schema_uri <- "https://schema.rtemis.org/a3/v1/schema.json"
		.a3_version <- "1.0.0"

	data = {k: v for k, v in data.items() if k not in _ENVELOPE_KEYS}
	for key in _ENVELOPE_KEYS:
	data.pop(key, None)

		@@ -166,6 +172,8 @@ describe("A3.toJSON and JSON.stringify", () => {

		it("type field is always present on annotation entries", () => {

Conversation

egenn commented Mar 31, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 31, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants