refactor: replaces allOf+if with clean oneOf structures#185
refactor: replaces allOf+if with clean oneOf structures#185
Conversation
WalkthroughThe JWT JSON schema ( Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @specs/jwt-schema.json:
- Around line 134-141: The "permissions" array in the JWT schema documents "The
provider address must be unique across all permissions entries," but JSON Schema
(draft-07) cannot enforce uniqueness of a specific property across array items;
update the "permissions" description to state this is a semantic/runtime
constraint (e.g., "Uniqueness of provider address across entries is validated at
runtime") or, if runtime validation already exists, retain the note that
uniqueness is enforced outside the schema; reference the "permissions" property
and the "lease-permission" definition when making the clarification.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
specs/jwt-schema.json
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
- GitHub Check: test
- GitHub Check: coverage
- GitHub Check: go
- GitHub Check: proto
🔇 Additional comments (7)
specs/jwt-schema.json (7)
17-51: Clean refactoring to reference-based definitions.The extraction of
akash-addressandleasesinto reusable definitions improves maintainability and ensures consistency. The description is correctly preserved alongside the$ref.
53-56: Address pattern is correct.The pattern correctly validates bech32 Akash addresses:
akash1prefix (6 chars) followed by 38 lowercase alphanumeric characters, totaling 44 characters as documented.
57-75: Well-structured action-scope definition.The combination of
minItems: 1,uniqueItems: true, and enum-constrained items correctly enforces a non-empty set of valid, unique actions.
76-90: Clean discriminated union using oneOf.The
oneOfstructure withconstdiscriminators on theaccessfield is the idiomatic JSON Schema pattern for discriminated unions. This aligns well with the PR objective and improves tooling support for type generation.
144-158: Consistent discriminated union pattern.The
lease-permissiondefinition mirrors theleasesstructure appropriately, providing a hierarchical permission model with the same full/scoped/granular access levels at the provider scope.
159-225: Provider permission variants are well-structured.Good reuse of the
akash-addressandaction-scopedefinitions. TheadditionalProperties: falseconstraint on all variants ensures strict validation.
226-270: Deployment permission structure with proper dependency constraint.The
dependencieskeyword correctly enforces thatoseqrequiresgseqto be present. The structure is comprehensive with proper constraints.Minor verification:
dseqhasminimum: 1whilegseqandoseqhaveminimum: 0. If sequence numbers in Akash consistently start from 1 (as deployment sequences appear to), consider aligninggseqandoseqto also haveminimum: 1. If 0-based indexing is intentional for group/order sequences, the current schema is correct.
|
PR failure will be fixed in #184 |
stalniy
force-pushed
the
refactor/provide-jwt-json-schema
branch
from
4e52bff to
44c7bed
Compare
stalniy
force-pushed
the
refactor/provide-jwt-json-schema
branch
from
44c7bed to
99397de
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@specs/jwt-schema.json`:
- Around line 17-19: The schema uses "$ref" with sibling "description" (e.g.,
the "iss" property and other occurrences) which draft-07 ignores; fix each by
replacing the direct "$ref" sibling pattern with an allOf array containing the
$ref and moving the description (and any other metadata like title/examples) as
siblings on the parent object—for example, change the "iss" property to an
object with "allOf": [ { "$ref": "#/definitions/akash-address" } ] and keep
"description" alongside "allOf"; apply this same transformation for all listed
properties so validators process both the referenced schema and the descriptive
metadata.
| "iss": { | ||
| "type": "string", | ||
| "pattern": "^akash1[a-z0-9]{38}$", | ||
| "$ref": "#/definitions/akash-address", | ||
| "description": "Akash address of the lease(s) owner, e.g., akash1abcd... (44 characters)" |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
JSON Schema draft-07 $ref sibling keywords behavior specification
💡 Result:
In JSON Schema draft-07, if a schema object contains $ref, it is treated purely as a reference, and all sibling keywords are ignored during evaluation/validation:
- “An object schema with a
$refproperty MUST be interpreted as a$refreference… All other properties in a$refobject MUST be ignored.” [1][2]
Implication: this draft-07 schema ignores type, properties, required, etc. because they are siblings of $ref:
{
"$ref": "#/definitions/Foo",
"type": "object",
"required": ["a"]
}Workaround (draft-07): combine constraints by moving $ref into an applicator such as allOf:
{
"allOf": [
{ "$ref": "#/definitions/Foo" },
{ "type": "object", "required": ["a"] }
]
}Spec references: JSON Schema Core draft-07, “Schema References With $ref” (section 8.3). [1][2]
Sources: [1] JSON Schema draft-07 core spec (json-schema.org) (json-schema.org), [2] IETF draft-handrews-json-schema-01 (datatracker) (datatracker.ietf.org)
Citations:
- 1: https://json-schema.org/draft-07/json-schema-core?utm_source=openai
- 2: https://datatracker.ietf.org/doc/html/draft-handrews-json-schema-01?utm_source=openai
Fix JSON Schema draft-07 $ref sibling keywords that will be ignored.
In JSON Schema draft-07, the specification explicitly requires that when a schema object contains $ref, all sibling keywords are completely ignored during validation. The description fields on lines 19, 116-119, 167-169, 186-189, 194-197, 209-212, and 240-243 will not be processed by spec-compliant validators.
To preserve both the reference and the description, wrap the $ref in an allOf:
Wrap $ref with description in allOf
"iss": {
- "$ref": "#/definitions/akash-address",
- "description": "Akash address of the lease(s) owner, e.g., akash1abcd... (44 characters)"
+ "allOf": [{ "$ref": "#/definitions/akash-address" }],
+ "description": "Akash address of the lease(s) owner, e.g., akash1abcd... (44 characters)"
},Apply the same pattern to all other occurrences listed above.
🤖 Prompt for AI Agents
In `@specs/jwt-schema.json` around lines 17 - 19, The schema uses "$ref" with
sibling "description" (e.g., the "iss" property and other occurrences) which
draft-07 ignores; fix each by replacing the direct "$ref" sibling pattern with
an allOf array containing the $ref and moving the description (and any other
metadata like title/examples) as siblings on the parent object—for example,
change the "iss" property to an object with "allOf": [ { "$ref":
"#/definitions/akash-address" } ] and keep "description" alongside "allOf";
apply this same transformation for all listed properties so validators process
both the referenced schema and the descriptive metadata.
3 participants
📝 Description
Using
oneOfinstead ofallOf + ifmakes it easier to see discriminated union in payload shape. Additionally, it improves tooling support, for example json-schema-to-typescript can generate correct types from oneOf schema and we don't need to write it manually.In terms of validation, it supports the same rules as the previous one. However error messages will be different.
🔧 Purpose of the Change
📌 Related Issues
✅ Checklist
I've updated relevant documentation📎 Notes for Reviewers
[Include any additional context, architectural decisions, or specific areas to focus on]