xsd-ui

Dynamic Angular form library for ISO 20022 workflows.

xsd-ui renders schema-driven forms from XSD-to-JSON metadata, supports recursive complex structures, validates according to schema constraints, and exports data as clean output JSON.

Why xsd-ui

• Schema-driven rendering for nested ISO 20022 structures
• Reactive Forms architecture with recursive field generation
• Built-in validation from schema rules (length, pattern, numeric constraints, enum)
• XML and JSON patching APIs (setXmlForm, setJsonForm)
• Output shaping with optional empty-field omission
• Event-based API access (onFormReadyEvent) without ViewChild
• Standalone Angular components, ready for library consumption

Installation

npm install xsd-ui

Peer dependencies:

• @angular/common ^21.2.10
• @angular/core ^21.2.10
• @angular/forms ^21.2.10
• @angular/animations ^21.2.10
• rxjs ^7.8.1

Quick Start

Register license once (recommended):

import {
  configureXsdUiLicense,
  XsdLicensePayload,
  XsdLicenseValidationResult,
  XsdLicenseValidator,
} from 'xsd-ui';

const validateLicenseOnServer: XsdLicenseValidator = async (
  licenseKey: string,
  payload: XsdLicensePayload,
): Promise<XsdLicenseValidationResult> => {
  const response = await fetch('/api/licenses/validate', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ licenseKey, payload }),
  });

  if (!response.ok) {
    return { valid: false, reason: 'License API unavailable.' };
  }

  return response.json() as Promise<XsdLicenseValidationResult>;
};

configureXsdUiLicense({
  licenseKey: '<YOUR_LICENSE_KEY>',
  licenseValidator: validateLicenseOnServer,
  requireServerValidation: true,
  offlineFallbackOnServerError: true,
});

Use component:

import { Component } from '@angular/core';
import {
  XsdFormComponent,
  XsdLicenseValidationResult,
  XsdFormPublicApi,
  XsdFormSchema,
} from 'xsd-ui';

@Component({
  selector: 'app-payment-form',
  standalone: true,
  imports: [XsdFormComponent],
  template: `
    <xsd-form
      [schema]="schema"
      (onFormReadyEvent)="onFormReady($event)"
      (licenseValidationChange)="onLicenseValidationChange($event)"
      (change)="onFormChange()"
    />

    <button type="button" (click)="submit()">Submit</button>
  `,
})
export class PaymentFormComponent {
  schema!: XsdFormSchema;
  formApi: XsdFormPublicApi | null = null;

  onFormReady(api: XsdFormPublicApi): void {
    this.formApi = api;
  }

  onFormChange(): void {
    // Live updates, autosave, previews, etc.
  }

  onLicenseValidationChange(result: XsdLicenseValidationResult): void {
    if (!result.valid) {
      console.error(result.reason);
    }
  }

  submit(): void {
    if (!this.formApi) return;
    if (!this.formApi.isValid()) return;

    const payload = this.formApi.getForm(true);
    console.log(payload);
  }
}

Core Components

• XsdFormComponent (xsd-form): root orchestration component
• XsdFieldComponent (xsd-field): recursive field renderer

Inputs

| Input | Type | Required | Description | |---|---|---|---| | schema | XsdFormSchema | Yes | Root schema including namespace and schemaElement. | | licenseKey | string | No | Optional override for global registered key. | | licenseValidator | XsdLicenseValidator | No | Optional override for global server validator. | | requireServerValidation | boolean | No | Optional override for global server-validation enforcement. | | offlineFallbackOnServerError | boolean | No | Optional override to allow offline fallback when server validation errors out. | | translations | TranslationConfig | No | Label and error message overrides. |

Outputs

| Output | Payload | Description | |---|---|---| | onFormReadyEvent | XsdFormPublicApi | Emits when form API is ready (and on schema rebuild). | | licenseValidationChange | XsdLicenseValidationResult | Emits license validation state and failure reason. | | change | void | Emits on value changes and programmatic updates. |

Licensing Best Practice

For browser libraries, client-side checks alone are not tamper-proof. Recommended production setup:

1. Register licensing once at app startup with configureXsdUiLicense(...).
2. Keep signed offline key verification enabled (licenseKey + RSA signature).
3. Add backend entitlement validation using licenseValidator.
4. Set requireServerValidation to true in production.
5. Keep offlineFallbackOnServerError enabled if you want graceful offline operation.
6. Return short-lived entitlements from your backend and rotate/revoke there.

Note: When implementing licenseValidator, return { valid: false } for explicit entitlement rejection (revoked, over-limit, wrong tenant), and throw errors for network/server failures. This lets xsd-ui distinguish deny vs fallback conditions.

This hybrid approach is the strongest practical model for Angular UI components.

Public API

Exposed through onFormReadyEvent.

| Method | Description | |---|---| | isValid(): boolean | Returns schema-aware validity (optional empty branches are handled). | | getForm(omitEmpty?: boolean) | Returns output JSON in root-keyed structure. | | setJsonForm(json) | Patches form using either full root-keyed JSON or inner object. | | setXmlForm(xml) | Parses and patches ISO 20022 XML payloads. | | getNamespace() | Returns schema namespace. | | clearForm() | Resets form values. | | disableForm() | Disables all controls. | | enableForm() | Enables all controls. |

Schema Model Overview

xsd-ui expects an XsdFormSchema shape similar to:

interface XsdFormSchema {
  namespace: string;
  schemaElement: SchemaElement | SchemaElement[];
}

Each SchemaElement contains metadata such as:

• name, id, xpath
• dataType
• cardinality: minOccurs, maxOccurs
• validation constraints: minLength, maxLength, pattern, minInclusive, maxInclusive, etc.
• structure: elements (children)

Validations Supported

• Required checks from minOccurs
• String length (minLength, maxLength)
• Regex pattern
• Numeric boundaries (minInclusive, maxInclusive, minExclusive, maxExclusive)
• fractionDigits, totalDigits
• Enumerations (values)
• Choice structures and unbounded arrays

XML / JSON Patching

JSON patch

formApi.setJsonForm({
  FIToFICstmrCdtTrf: {
    GrpHdr: {
      MsgId: 'MSG-001',
      CreDtTm: '2026-04-25T12:41:52.673+08:00',
      NbOfTxs: '1'
    }
  }
});

XML patch

formApi.setXmlForm(`
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pacs.008.001.08">
  <FIToFICstmrCdtTrf>
    <GrpHdr>
      <MsgId>XML-PATCH-001</MsgId>
      <NbOfTxs>1</NbOfTxs>
    </GrpHdr>
  </FIToFICstmrCdtTrf>
</Document>
`);

License

This package is distributed under a commercial license. Contact the publisher for licensing terms and usage rights.