docs(architecture): add ADR-0008 map-file schema specification - #212
Conversation
Defines the formal JSON Schema v1 for the map-file format: - Root structure: $schema (IDE autocomplete) + $config (config/metadata) + variables - Reserved $ prefix rule: parsers MUST ignore all $-prefixed keys - $config strict fields: provider, profile, vaultUrl, projectId, path, namespace + metadata - file provider for consumer testing via EnvilderOptions.FromFile(path) - One file = one provider = one environment - Variable name pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$ - additionalProperties: false on $config Also updates ADR index in common-architecture-decisions SKILL.
|
Warning Rate limit exceeded
To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (1)
WalkthroughThis PR adds ADR-0008, a comprehensive architecture decision record documenting Envilder's v1 map-file schema specification. The ADR defines the root structure, optional configuration fields, variable mapping semantics across providers (AWS, Azure, GCP, HashiCorp, and a new ChangesADR-0008 Map File Schema Specification
Estimated code review effort🎯 2 (Simple) | ⏱️ ~15 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip 💬 Introducing Slack Agent: Turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. 👉 Get your free trial and get 200 agent minutes per Slack user (a $50 value). Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Review rate limit: 0/1 reviews remaining, refill in 22 minutes and 43 seconds.Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces ADR-0008, which formalizes the Map-File Schema Specification for Envilder. The new specification defines a JSON schema, reserved keys (prefixed with $), and a new file provider to facilitate local testing without cloud infrastructure. Review feedback identified several areas for improvement, including correcting terminology inconsistencies between documentation and code examples, fixing a typo in the backward compatibility section, addressing a potential breaking change regarding variable naming constraints, and suggesting a more comprehensive approach to cross-provider validation rules.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/architecture/adr/0008-map-file-schema.md`:
- Around line 167-171: The ADR currently states the schema "is published" at
`https://envilder.com/schema/map-file.v1.json` and "lives in the repository at
`spec/map-file.v1.json`" but the PR intends publication as a follow-up; update
the wording to future/planned tense (e.g., "will be published" / "will live") or
add an "implementation status" note indicating publication is pending, and
preserve the references to `$schema` and absence of a `version` field so readers
know files without a `$schema` are assumed v1 until the schema URL and
`spec/map-file.v1.json` are actually published.
- Around line 75-87: Section 4's "One File, One Provider, One Environment" claim
conflicts with the `environment` metadata being optional/ignored; update the ADR
text to be explicit: either state this is a non-enforced convention (leave
`environment` optional/ignored) or mandate enforcement and describe the
mechanism (e.g., add schema validation that requires `environment`, runtime
validation in map-loading code, or a filename/naming convention that tooling
enforces). Reference the `environment` field and the Section 4 heading ("One
File, One Provider, One Environment") in your change and include the chosen
enforcement details (schema key name, validation step, or naming rule) so
readers know whether the rule is contractual or merely advisory.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: dd246dbe-d3c9-4776-9bc2-ac2db36e9f58
⛔ Files ignored due to path filters (1)
.github/skills/common-architecture-decisions/SKILL.mdis excluded by none and included by none
📒 Files selected for processing (1)
docs/architecture/adr/0008-map-file-schema.md
There was a problem hiding this comment.
Pull request overview
This PR adds ADR-0008 to formally define the map-file schema as a shared contract across Envilder’s CLI, GitHub Action, and SDKs, and updates the architecture skill index to reference the new decision. It is primarily documentation/architecture work that sets direction for later implementation across stacks.
Changes:
- Add ADR-0008 describing the proposed map-file JSON Schema v1, reserved-key rules, provider/config fields, and testing-oriented
fileprovider design. - Document cross-provider validation and publication/versioning expectations for the schema.
- Update the architecture decision skill index to include newer ADR entries, including ADR-0008.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
docs/architecture/adr/0008-map-file-schema.md |
New ADR defining the proposed map-file schema, provider fields, reserved $ behavior, and follow-on implementation direction. |
.github/skills/common-architecture-decisions/SKILL.md |
Expands the ADR index so the shared architecture skill references newer decision records. |
|
@copilot resolve the merge conflicts in this pull request |
The merge conflicts were already resolved in commit |
…le-schema # Conflicts: # .github/skills/common-architecture-decisions/SKILL.md
- Fix WithDefaults → WithOverride terminology consistency - Fix → typo in backward compatibility section - Relax variable naming regex to advisory SHOULD (non-breaking) - Add general cross-provider validation rule with exhaustive field table - Clarify 'One Environment' as organizational convention, not enforced - Change schema publication to future tense (pending follow-up) - Note gcp/hashicorp providers as planned, not yet implemented - Add Node.js implementation note for overload resolution
- Add proposed API note to section 6 (file provider examples) - Mark SKILL.md ADR-0008 entry with (planned) for unimplemented APIs
| **Backward compatibility:** Existing map files (without `$schema` or `$config`) | ||
| work identically. The only behavioral change: SDKs stop making vault calls for | ||
| `$schema` values that would previously leak through as variable mappings. |
| ```python | ||
| # Python | ||
| Envilder.load("param-map.json", EnvilderOptions.from_file(".env.test")) |
| | [ADR-0005](../../../docs/architecture/adr/0005-sdk-integration-tiers.md) | SDK Integration Tiers | All SDKs | Three tiers (Facade, Builder, Framework); Tier 3 separate package; .NET exception; community-driven | | ||
| | [ADR-0006](../../../docs/architecture/adr/0006-monorepo-structure.md) | Monorepo Structure | All components | Single repo, independent releases per component via version-bump detection, no orchestrator | | ||
| | [ADR-0007](../../../docs/architecture/adr/0007-trunk-based-development.md) | Trunk-Based Development | All components | Single main branch, short-lived feature branches, squash merge, feature flags for incomplete work | | ||
| | [ADR-0008](../../../docs/architecture/adr/0008-map-file-schema.md) | Map-File Schema Specification | All components | JSON Schema v1, `$` prefix reserved, `$config` strict fields, `file` provider for testing (planned), `EnvilderOptions.FromFile` (planned) | |
| SDKs MUST reject any provider-specific `$config` field that does not belong to | ||
| the active provider. Each field has exactly one valid provider: | ||
|
|
||
| | Field | Valid provider(s) | | ||
| | ----- | ----------------- | | ||
| | `profile` | `aws` | | ||
| | `vaultUrl` | `azure`, `hashicorp` | | ||
| | `projectId` | `gcp` | | ||
| | `namespace` | `hashicorp` | | ||
| | `path` | `file` | |
| | `provider` | enum | `aws`, `azure`, `gcp`, `hashicorp`, `file` | Secret provider. Default: `aws`. Note: `gcp` and `hashicorp` are planned — not yet implemented in CLI or SDKs | | ||
| | `profile` | string | AWS-only | AWS CLI profile name | | ||
| | `vaultUrl` | string (URI) | Azure/HashiCorp-only | Vault endpoint URL | | ||
| | `projectId` | string | GCP-only | GCP project identifier | | ||
| | `path` | string | File-only | Path to `.env` source file | | ||
| | `namespace` | string | HashiCorp-only | Vault namespace | | ||
|
|
| All fields are optional. `additionalProperties: false` — unknown fields are | ||
| rejected to catch typos. |
Summary
Defines the formal JSON Schema v1 for the map-file format — the universal contract between CLI, GitHub Action, and all runtime SDKs.
Key Decisions
$schema(IDE autocomplete) +$config(config + metadata) + variables$prefix: parsers MUST ignore all$-prefixed keys (replaces exact-match on$config)$configstrict fields: provider, profile, vaultUrl, projectId, path, namespace + metadata (name, description, owner, environment)fileprovider: enables consumer testing without cloud infrastructure viaEnvilderOptions.FromFile(path)^[a-zA-Z_][a-zA-Z0-9_]*$additionalProperties: falseon$configto catch typosFollow-up Work
spec/map-file.v1.json$configmatch to$prefix filterfileprovider in each SDKEnvilderOptions.FromFilein each SDKhttps://envilder.com/schema/map-file.v1.jsonSummary by CodeRabbit