@stripe/extensibility-jsonschema-tools 1.0.0 → 1.0.1

package/dist/index.d.ts

@@ -279,6 +279,23 @@ declare interface MetadataValueRequireExplicitPolicyInput$2 {
 
 
 
+/**
+ * Controls whether a type-level annotation can flow from a base declaration to
+ * a derived declaration during semantic analysis.
+ *
+ * @public
+ */
+declare type AnnotationInheritancePolicy$1 = "local-wins" | "never";
+
+/**
+ * Controls whether a type-level annotation can flow from a base declaration to
+ * a derived declaration during semantic analysis.
+ *
+ * @public
+ */
+declare type AnnotationInheritancePolicy_2 = "local-wins" | "never";
+
+
 /**
  * Registration for mapping a built-in TSDoc tag onto a custom constraint when
  * it is used on a particular custom type.
@@ -364,24 +381,6 @@ declare interface Category {
 }
 
 
-/**
- * Complete constraint configuration for a FormSpec project.
- *
- * @public
- */
-declare interface ConstraintConfig {
-    /** Field type constraints */
-    fieldTypes?: FieldTypeConstraints;
-    /** Layout and structure constraints */
-    layout?: LayoutConstraints;
-    /** UI Schema feature constraints */
-    uiSchema?: UISchemaConstraints;
-    /** Field configuration option constraints */
-    fieldOptions?: FieldOptionConstraints;
-    /** Control options constraints */
-    controlOptions?: ControlOptionConstraints;
-}
-
 /**
  * Semantic metadata for ordered custom constraints that should participate in
  * the generic contradiction/broadening logic.
@@ -480,7 +479,7 @@ declare interface ControlElement {
 }
 
 /**
- * Control options constraints - control which JSONForms Control.options are allowed.
+ * Control options constraints - control which JSON Forms Control.options are allowed.
  * These are renderer-specific options that may not be universally supported.
  *
  * @public
@@ -511,6 +510,19 @@ declare interface ControlOptionConstraints {
 declare interface CustomAnnotationRegistration_2 {
     /** The annotation name, unique within the extension. */
     readonly annotationName: string;
+    /**
+     * Optional type-level inheritance behavior for semantic consumers.
+     *
+     * `"local-wins"` means a derived declaration inherits this annotation from
+     * its base declaration only when the derived declaration does not provide the
+     * same extension annotation identity locally. Omitted registrations behave as
+     * `"never"`.
+     */
+    readonly inheritFromBase?: AnnotationInheritancePolicy$1;
+    /**
+     * Optional editor documentation for the annotation's TSDoc authoring tag.
+     */
+    readonly tagDocumentation?: CustomAnnotationTagDocumentation$1;
     /**
      * Optionally converts the annotation value into JSON Schema keywords.
      * If omitted, the annotation has no JSON Schema representation (UI-only).
@@ -529,6 +541,19 @@ declare interface CustomAnnotationRegistration_2 {
 declare interface CustomAnnotationRegistration_3 {
     /** The annotation name, unique within the extension. */
     readonly annotationName: string;
+    /**
+     * Optional type-level inheritance behavior for semantic consumers.
+     *
+     * `"local-wins"` means a derived declaration inherits this annotation from
+     * its base declaration only when the derived declaration does not provide the
+     * same extension annotation identity locally. Omitted registrations behave as
+     * `"never"`.
+     */
+    readonly inheritFromBase?: AnnotationInheritancePolicy_2;
+    /**
+     * Optional editor documentation for the annotation's TSDoc authoring tag.
+     */
+    readonly tagDocumentation?: CustomAnnotationTagDocumentation_2;
     /**
      * Optionally converts the annotation value into JSON Schema keywords.
      * If omitted, the annotation has no JSON Schema representation (UI-only).
@@ -536,6 +561,56 @@ declare interface CustomAnnotationRegistration_3 {
     readonly toJsonSchema?: (value: ExtensionPayloadValue_2, vendorPrefix: string) => Record<string, unknown>;
 }
 
+/**
+ * Documentation text for an extension annotation's TSDoc authoring tag.
+ *
+ * These strings are consumed by editor integrations for completion details and
+ * hover text. They do not affect annotation parsing, inheritance, or schema
+ * emission.
+ *
+ * @public
+ */
+declare interface CustomAnnotationTagDocumentation$1 {
+    /** Completion detail shown beside the annotation tag. */
+    readonly completionDetail?: string;
+    /**
+     * Label for the payload portion of the annotation tag signature.
+     *
+     * The payload remains the full authored text after the tag name, so this can
+     * describe single-argument or multi-argument annotation syntaxes.
+     */
+    readonly payloadLabel?: string;
+    /** Short hover summary shown for the annotation tag. */
+    readonly hoverSummary?: string;
+    /** Full markdown hover body for the annotation tag. */
+    readonly hoverMarkdown?: string;
+}
+
+/**
+ * Documentation text for an extension annotation's TSDoc authoring tag.
+ *
+ * These strings are consumed by editor integrations for completion details and
+ * hover text. They do not affect annotation parsing, inheritance, or schema
+ * emission.
+ *
+ * @public
+ */
+declare interface CustomAnnotationTagDocumentation_2 {
+    /** Completion detail shown beside the annotation tag. */
+    readonly completionDetail?: string;
+    /**
+     * Label for the payload portion of the annotation tag signature.
+     *
+     * The payload remains the full authored text after the tag name, so this can
+     * describe single-argument or multi-argument annotation syntaxes.
+     */
+    readonly payloadLabel?: string;
+    /** Short hover summary shown for the annotation tag. */
+    readonly hoverSummary?: string;
+    /** Full markdown hover body for the annotation tag. */
+    readonly hoverMarkdown?: string;
+}
+
 
 /**
  * Registration for a custom constraint that maps to JSON Schema keywords.
@@ -795,6 +870,24 @@ declare interface DiscriminatorResolutionOptions {
     readonly apiNamePrefix?: string | undefined;
 }
 
+/**
+ * Complete DSL policy for a FormSpec project.
+ *
+ * @public
+ */
+declare interface DSLPolicy {
+    /** Field type constraints */
+    fieldTypes?: FieldTypeConstraints;
+    /** Layout and structure constraints */
+    layout?: LayoutConstraints;
+    /** UI schema feature constraints */
+    uiSchema?: UISchemaConstraints;
+    /** Field configuration option constraints */
+    fieldOptions?: FieldOptionConstraints;
+    /** Control options constraints */
+    controlOptions?: ControlOptionConstraints;
+}
+
 
 /**
  * Enum-member display names remain unset unless authored explicitly.
@@ -1169,8 +1262,7 @@ declare interface FieldTypeConstraints {
 
 
 /**
- * Top-level FormSpec configuration file structure.
- * The .formspec.yml file uses this structure.
+ * Top-level FormSpec configuration structure.
  *
  * @public
  */
@@ -1180,9 +1272,11 @@ declare interface FormSpecConfig {
      * annotations, and vocabulary keywords.
      */
     readonly extensions?: readonly ExtensionDefinition_3[];
-    /** Constraint surface configuration — controls which field types,
-     * layouts, UI features, and field/control options are allowed. */
-    readonly constraints?: ConstraintConfig;
+    /**
+     * DSL-policy surface configuration controlling which field types,
+     * layouts, UI features, and field/control options are allowed.
+     */
+    readonly constraints?: DSLPolicy;
     /**
      * Metadata inference and naming policy. Controls how apiName,
      * displayName, and plural forms are derived when not authored.
@@ -1202,6 +1296,11 @@ declare interface FormSpecConfig {
      * @defaultValue "enum"
      */
     readonly enumSerialization?: "enum" | "oneOf" | "smart-size";
+    /**
+     * JSON Schema serialization settings for vocabulary and dialect emission.
+     * PR-1 stores and resolves this block; PR-2 consumes it.
+     */
+    readonly serialization?: FormSpecSerializationConfig;
     /**
      * Per-package configuration overrides for monorepos.
      * Keys are glob patterns matched against file paths relative to
@@ -1217,14 +1316,31 @@ declare interface FormSpecConfig {
  * @public
  */
 declare interface FormSpecPackageOverride {
-    /** Override constraint surface for this package. */
-    readonly constraints?: ConstraintConfig;
+    /** Override DSL policy for this package. */
+    readonly constraints?: DSLPolicy;
     /** Override enum serialization for this package. */
     readonly enumSerialization?: "enum" | "oneOf" | "smart-size";
     /** Override metadata policy for this package. */
     readonly metadata?: MetadataPolicyInput_2;
 }
 
+/**
+ * Forward-looking JSON Schema serialization settings.
+ *
+ * These values are currently carried through configuration for future
+ * vocabulary and dialect emission.
+ *
+ * @public
+ */
+declare interface FormSpecSerializationConfig {
+    /** Base URL used to construct default FormSpec vocabulary URLs. */
+    readonly vocabularyBaseUrl?: string;
+    /** Per-vocabulary URL overrides keyed by vocabulary identifier. */
+    readonly vocabularyUrls?: Readonly<Record<string, string>>;
+    /** Explicit FormSpec dialect URL override. */
+    readonly dialectUrl?: string;
+}
+
 /**
  * Options for generating schemas from a decorated class.
  *
@@ -1391,6 +1507,8 @@ declare interface JsonSchema2020 {
     description?: string;
     /** Default value suggested for the schema node. */
     default?: unknown;
+    /** Documentation example values (from one or more `@example` tags). */
+    examples?: unknown[];
     /** Whether the schema node is deprecated. */
     deprecated?: boolean;
     /** Additional vendor-prefixed extension keywords. */
@@ -1430,7 +1548,7 @@ declare interface LayoutConstraints {
 }
 
 /**
- * JSONForms layout type constraints.
+ * JSON Forms layout type constraints.
  *
  * @public
  */
@@ -1826,7 +1944,7 @@ declare interface RuleConditionSchema {
 }
 
 /**
- * JSONForms rule constraints.
+ * JSON Forms rule constraints.
  *
  * @public
  */
@@ -1853,7 +1971,7 @@ declare interface RuleConstraints {
 declare type RuleEffect = "SHOW" | "HIDE" | "ENABLE" | "DISABLE";
 
 /**
- * JSONForms rule effect constraints.
+ * JSON Forms rule effect constraints.
  *
  * @public
  */
@@ -1880,8 +1998,10 @@ declare interface SchemaBasedCondition {
     readonly schema: RuleConditionSchema;
 }
 
+/* Excluded from this release type: SetupDiagnostic */
+
 /**
- * Severity level for constraint violations.
+ * Severity level for DSL-policy violations.
  * - "error": Violation fails validation
  * - "warn": Violation emits warning but passes
  * - "off": Feature is allowed (no violation)
@@ -1953,7 +2073,7 @@ declare interface StaticSchemaGenerationOptions {
 declare type UISchema = VerticalLayout | HorizontalLayout | GroupLayout | Categorization;
 
 /**
- * UI Schema feature constraints - control JSONForms-specific features.
+ * UI schema feature constraints - control JSON Forms-specific features.
  *
  * @public
  */
@@ -2036,6 +2156,14 @@ declare function _generateSchemas(options: Omit<GenerateSchemasOptions, 'errorRe
  */
 declare function _fixupDecimalPathConstraints(schema: JsonSchema2020): JsonSchema2020;
 
+/**
+ * Controls whether a type-level annotation can flow from a base declaration to
+ * a derived declaration during semantic analysis.
+ *
+ * @public
+ */
+declare type AnnotationInheritancePolicy = "local-wins" | "never";
+
 /**
  * Registration for mapping a built-in TSDoc tag onto a custom constraint when
  * it is used on a particular custom type.
@@ -2115,6 +2243,19 @@ declare interface ConstraintTagRegistration {
 declare interface CustomAnnotationRegistration {
     /** The annotation name, unique within the extension. */
     readonly annotationName: string;
+    /**
+     * Optional type-level inheritance behavior for semantic consumers.
+     *
+     * `"local-wins"` means a derived declaration inherits this annotation from
+     * its base declaration only when the derived declaration does not provide the
+     * same extension annotation identity locally. Omitted registrations behave as
+     * `"never"`.
+     */
+    readonly inheritFromBase?: AnnotationInheritancePolicy;
+    /**
+     * Optional editor documentation for the annotation's TSDoc authoring tag.
+     */
+    readonly tagDocumentation?: CustomAnnotationTagDocumentation;
     /**
      * Optionally converts the annotation value into JSON Schema keywords.
      * If omitted, the annotation has no JSON Schema representation (UI-only).
@@ -2122,6 +2263,31 @@ declare interface CustomAnnotationRegistration {
     readonly toJsonSchema?: (value: ExtensionPayloadValue, vendorPrefix: string) => Record<string, unknown>;
 }
 
+/**
+ * Documentation text for an extension annotation's TSDoc authoring tag.
+ *
+ * These strings are consumed by editor integrations for completion details and
+ * hover text. They do not affect annotation parsing, inheritance, or schema
+ * emission.
+ *
+ * @public
+ */
+declare interface CustomAnnotationTagDocumentation {
+    /** Completion detail shown beside the annotation tag. */
+    readonly completionDetail?: string;
+    /**
+     * Label for the payload portion of the annotation tag signature.
+     *
+     * The payload remains the full authored text after the tag name, so this can
+     * describe single-argument or multi-argument annotation syntaxes.
+     */
+    readonly payloadLabel?: string;
+    /** Short hover summary shown for the annotation tag. */
+    readonly hoverSummary?: string;
+    /** Full markdown hover body for the annotation tag. */
+    readonly hoverMarkdown?: string;
+}
+
 /* Excluded from this release type: CustomConstraintNode */
 
 /**