docs(resources): document static properties as a first-class MCP/OpenAPI schema source#605
docs(resources): document static properties as a first-class MCP/OpenAPI schema source#605kylebernhardy wants to merge 5 commits into
Conversation
…API schema source
Harper 5.2.0 makes a programmatic Resource's `static properties` drive the
MCP tool schemas, the OpenAPI document, and `harper://schema` — previously
those surfaces read only the internal `attributes` Array, so a bare
`static properties` declaration produced a skeletal `{ type: 'object' }`.
5.2.0 also resolves `GET /Resource/id.property` against `static properties`.
Documents the authoring path: the JSON Schema vocabulary (lowercase types,
distinct from the capitalized GraphQL names), the full fragment key list,
how unions/item-less arrays/optional properties resolve, and a nested +
array-of-object example.
Companion to HarperFast/harper#1921 and #1933; closes HarperFast/harper#1923.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0188G62J9fZQg4J9rVuqLzjy
![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 updates the documentation across several files to reflect changes in version v5.2.0, specifically detailing how programmatic Resources declaring static properties now receive rich schema generation across MCP, OpenAPI, and schema introspection surfaces. It adds comprehensive explanations of JSON Schema vocabulary, an authoring rubric, and examples. Feedback on the changes suggests updating the get method in the OrderSummary example to be a static method to maintain consistency with Harper Resource documentation standards.
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-605 This preview will update automatically when you push new commits. |
Adversarial fact-check of every technical claim in the previous commit
against harper core turned up 15 defects. Corrections:
- harper://schema is keyed by database/table, so a table-less programmatic
Resource never appears there; dropped it from the surface list.
- Only get_* has a record-shaped outputSchema. search_* has none; the write
verbs advertise fixed {id}/{ok}/{deleted} envelopes. update_*/patch_* are
mutually exclusive.
- Nullability: MCP re-expands to type:['string','null'] and never emits a
`nullable` keyword; OpenAPI drops it at the top level and emits it only
inside nested objects.
- enum/format/const and per-property hidden are honored at the top level;
nested/items keep them on MCP but not OpenAPI. Timestamp keys are MCP-only.
- The OpenAPI path parameter and the verb-description sentence read the
class-level `static primaryKey`, not the fragment flag — document both.
- Capitalized GraphQL type names DO map correctly; the real hazard is a name
in neither vocabulary, where the two surfaces disagree.
- Corrected the get_ProductInventory sample to the actual emitted shape
(pk description override, get_attributes description, required +
additionalProperties on the output schema).
- Added the super-user-only listing caveat for table-less Resources.
- Fixed a pre-existing claim that attribute_permissions filters tool schemas
per-user; schemas are built once at registration and are user-agnostic.
- REST: .json/.cbor/.msgpack/.csv take precedence over a same-named property.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0188G62J9fZQg4J9rVuqLzjy
…contradicted it Conventions/consistency pass found three pages stating the old rule, none of which the first pass touched: - reference/mcp/overview.md said input schemas are "narrowed by your role's attribute_permissions" — they are not; schemas are built once at registration and are caller-agnostic. Corrected, plus the static properties source. - reference/mcp/tools-and-resources.md said input schemas come from Table.attributes only. - reference/rest/querying.md is the canonical page for the `id.property` URL form and still said "declared in the schema"; rest/overview.md restated the same rule 26 lines above the one this PR had updated. Also: moved the Path B version badge off the (unchanged) section heading onto the paragraph it describes, and gave the ProductInventory example the `static primaryKey` its sample output already assumed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0188G62J9fZQg4J9rVuqLzjy
|
The three core-behavior gaps flagged in the description are now filed against v5.2:
These pages document current behavior, so each of those fixes will need a small follow-up edit here — the per-surface caveats in the fragment-key table collapse back to single rows once #1942 lands, the "top-level only" wording goes away with #1941, and the listing-visibility note changes with #1940. Each issue names the specific docs text to revisit. Comment generated by kAIle (Claude Opus 4.8). |
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-605 This preview will update automatically when you push new commits. |
… examples The examples in this section defined `get` as an instance method while the page's own primary examples (and the Resource Static Methods section above) use `static get(target)` — the documented override point. Converts all five, not just the one added by this PR. Flagged by gemini-code-assist on documentation#605. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0188G62J9fZQg4J9rVuqLzjy
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-605 This preview will update automatically when you push new commits. |
…ing instance Verified by booting Harper with a programmatic static-properties component and hitting the endpoints: - The route is `/openapi`, not `/openapi.json` — the latter 404s. Four references corrected, two of which this PR introduced. The integration suite uses `/openapi`, which is the authority. - "OpenAPI is typically exposed to anyone reachable on the HTTP port" overstates it: a default `prod` install returns 403 for an unauthenticated GET. What is actually true, and what matters for the @hidden guidance, is that the document is global — no per-user filtering — so any authorized caller sees every docstring regardless of their own read permissions. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0188G62J9fZQg4J9rVuqLzjy
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-605 This preview will update automatically when you push new commits. |
2 participants
Companion docs for harper#1921 —
feat(mcp/openapi): drive schemas from a programmatic Resource's static propertiesand harper#1933 —fix(resources): URL attribute-suffix routing for programmatic static-properties Resources. Closes HarperFast/harper#1923.What changed in core
static propertieshas been the canonical class-level metadata API since #1167, and the docs already described it — but only table-backed Resources actually got rich schemas from it. The MCP tool builder and the OpenAPI generator both read the internalattributesArray, so a programmatic Resource declaring a barestatic propertiesliteral produced an empty property set. 5.2.0 fixes that, and also resolvesGET /Resource/id.propertyagainststatic properties.So this is less "document a new API" than "the documented API now works for the case the docs implied it did" — plus the vocabulary, constraint, and per-surface details an author actually needs.
Changes
reference/resources/resource-api.md— the bulk of it. Understatic properties: which surfaces derive from it (and which explicitly don't), a JSON Schema vocabulary subsection, a table of every fragment key Harper reads with its per-surface behavior, resolution notes for unions / item-less arrays / optional properties /static primaryKey, and a nested-object + array-of-object example.learn/developers/mcp-and-openapi-metadata.mdx— Path B gets the emittedtools/listJSON, a vocabulary warning, a Path-B authoring rubric, and debugging guidance.reference/mcp/tool-metadata.md,reference/mcp/tools-and-resources.md,reference/mcp/overview.md— the three places that said input schemas come fromTable.attributes.reference/rest/overview.md,reference/rest/querying.md— theGET /MyTable/123.propertyNamerule, in both places it's stated.Review history worth knowing about
The first commit (
7fea797) was fact-checked against the implementation and 15 of its claims were wrong;6cfe041and556106bcorrect them. If you reviewed the first commit, please re-read rather than diffing. The corrections that matter most, because each is a per-surface asymmetry a reader would not guess:harper://schema/{db}/{table}is keyed by database/table, so a table-less programmatic Resource never appears there. It is not one of the surfaces.get_*has a record-shapedoutputSchema.search_*has none; the write verbs advertise fixed{id}/{ok}/{deleted}envelopes.update_*andpatch_*are mutually exclusive.type: ["string","null"]and never emits anullablekeyword; OpenAPI 3.0.3 drops it at the top level and emits it only inside nested objects.enum/format/constand per-propertyhiddenare honored at the top level only; inside a nested object or an array'sitems, MCP keeps them and OpenAPI drops them.static primaryKey(default'id'), not the fragment'sprimaryKey: true. Both examples now declare both.String,Int) do map correctly; the real hazard is a name in neither vocabulary ('Text'), where MCP coerces tostringand OpenAPI emits{}.Open items for a human
mcp/overview.mdand the metadata guide both saidattribute_permissionsnarrows MCP input schemas per user — every derivation call site passesundefined; schemas are built once at registration and are caller-agnostic (RBAC filters the tool list, and is enforced at call time). Shout if you'd rather split those out.<VersionBadge version="v5.2.0" />is the first v5.2.0 badge in the repo, and there's norelease-notes/v5-lincoln/5.2.mdyet — I didn't create one for a single entry. Happy to add it once that page exists.makeVisibleToreturnsfalsewithout a db/table),hiddenon a nested sub-property isn't suppressed (OpenAPI even emitshidden: trueas a schema key), and the two surfaces disagree on unknown type names. The docs describe current behavior; if any of these get fixed, these pages need a follow-up.Verified with
npm run build(clean; the one reported broken anchor is pre-existing onrelease-notes/v5-lincoln/5.1) andnpm run format:check.PR description generated by kAIle (Claude Opus 4.8).