Repository navigation
docs: teach purview-architecture to choose a contract strategy - #8
Merged
Merged
Conversation
Add a decision procedure for how an HTTP API and its clients share a contract (Contracts, OpenAPI or Hybrid), with version-skew rules, BFF guidance and worked examples. Add Bff to the architecture policy and the Project Responsibilities catalogue so the skill does not describe a responsibility the policy does not define.
ZodSharp exports JSON Schema but ships no OpenAPI integration, so the Hybrid strategy now says the API host wires the export into the document. It also covers x-zodsharp-unsupported, and the way additionalProperties: false breaks additive versioning for clients that validate responses strictly. Browser-safety now names mechanisms that actually check it: policy bans on ASP.NET Core packages and the framework reference, IsAotCompatible, and SupportedPlatform browser. It also says plainly that the analyzers only warn unless TreatWarningsAsErrors is set. The BFF section now covers the Blazor case, where the BFF is the host that serves the WebAssembly client (Bff may reference WebApp). It adds anti-forgery, cookie flags, Data Protection keys, server-side refresh, a server-side session store, and prerendering as the reason a BFF references Contracts.
…dds it Revert the architecture policy and Project Responsibilities wiki changes. BFF and Blazor support will arrive with a future Build SDK release, so for now the skill states the BFF and browser-safety rules as guidance and review obligations rather than as policy the playbook enforces.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a procedure to the
purview-architectureskill for deciding how an HTTP API and its clients share a contract: Contracts, OpenAPI or Hybrid. It also covers when a Backend-for-Frontend (BFF) is earned.Skills only. The architecture policy and the wiki are unchanged. Blazor and BFF support is planned for a future Build SDK release, so until then the skill states the BFF and browser-safety rules as guidance and review obligations.
Changes
skills/purview-architecture/references/contract-strategy.md(new):SKILL.md: a new section 5 summarising the strategy choice, plus a checklist item and a wider description.references/project-responsibilities.md: the Contracts and WebApp rows mention the Blazor WebAssembly client, and the split rule points to the new reference. The BFF guidance is in a section marked as not yet policy.Checked against the sources
{T}Schema.BuildJsonSchema(),x-zodsharp-unsupported,additionalProperties: falseandIsAotCompatibleare checked against zodsharpmain. ZodSharp ships no OpenAPI integration, so the skill says the API host wires the export into the document.Test run
just test: 74 passed, 1 skipped (an existing data-source skip), 0 failed.