@antglobal/copilot-cards-core 1.0.4 → 1.0.6

package/README.md

@@ -48,6 +48,63 @@ const greeting = resolveExpression("Hello, ${user.name}!", schema.variables);
 console.log(tree, greeting);
 ```
 
+## Structured and source-located validation
+
+Core exposes two structured validators for different input stages:
+
+| Input | API | Import path | Result |
+| --- | --- | --- | --- |
+| An already parsed Schema object | `validateSchemaDetailed` | `@antglobal/copilot-cards-core` | `SchemaValidationIssue[]` |
+| Raw JSON source text | `validateSchemaText` | `@antglobal/copilot-cards-core/validation-text` | `SchemaTextValidationResult` |
+
+`validation-text` is an optional package subpath, not a function name. There is
+no `validateText` export. Keeping this API in a separate entry point prevents
+render-only Core consumers from bundling `jsonc-parser`.
+
+`validateSchema(schema)` remains the compatible `string[]` API. Use
+`validateSchemaDetailed(schema)` when an integration needs stable error codes,
+RFC 6901 JSON Pointer paths, and localization parameters:
+
+```ts
+import {
+  validateSchemaDetailed,
+  type SchemaValidationIssue,
+} from "@antglobal/copilot-cards-core";
+
+const issues: SchemaValidationIssue[] = validateSchemaDetailed(schema);
+// [{ code, path, anchorPath?, message, params? }]
+```
+
+JSON editors can opt into strict parsing and source ranges through a separate
+entry point, keeping parser code out of render-only Core bundles:
+
+```ts
+import {
+  validateSchemaText,
+  type SchemaTextValidationResult,
+} from "@antglobal/copilot-cards-core/validation-text";
+
+const result: SchemaTextValidationResult = validateSchemaText(jsonText);
+if (!result.valid) {
+  for (const issue of result.errors) {
+    console.log(issue.code, issue.path, issue.range);
+  }
+} else {
+  // The successful result already contains the parsed Schema.
+  render(result.schema);
+}
+```
+
+Lines and columns are 1-based; offsets are 0-based JavaScript UTF-16 offsets.
+The text API rejects comments, trailing commas, duplicate properties, inputs
+over 1,000,000 characters, and nesting deeper than 128 levels. It returns at
+most 50 diagnostics and sets `truncated: true` when more exist.
+
+Core validates only shared SDK protocol such as roots, slots, references and
+Repeat bindings. It deliberately does not validate component registration,
+custom component props, host actions/events, injected variables, or expression
+result types, so custom component JSON is not rejected for business-owned data.
+
 ## Capabilities
 
 | Module | Purpose |