@f1studio/form-spec 5.0.0-alpha.101 → 5.0.0-alpha.103

package/README.TS.md

@@ -1,622 +1,622 @@
-# FormSpec TypeScript API Documentation
-
-## 🚀 F# to TypeScript Interop for Form Specifications
-
-The FormSpec TypeScript API provides a type-safe, validated bridge between F# domain models and TypeScript applications. Built with Fable and Thoth.Json, it enables seamless form specification management across the F#/TypeScript boundary.
-
-## Installation
-
-```bash
-# From Verdaccio local registry
-npm install @f1studio/form-spec@5.0.0-alpha.13 --registry http://localhost:4873
-# or
-pnpm add @f1studio/form-spec@5.0.0-alpha.13 --registry http://localhost:4873
-# or
-yarn add @f1studio/form-spec@5.0.0-alpha.13 --registry http://localhost:4873
-```
-
-## Core Concepts
-
-### FableResult Type
-All validation functions return a `FableResult<T, E>` - a TypeScript-friendly tagged union:
-
-```typescript
-type FableResult<T, E> =
-  | { result: "fableOk"; Item: T }
-  | { result: "fableError"; Item: E }
-```
-
-This enables safe pattern matching in TypeScript:
-
-```typescript
-const result = validateFormSpec(unknownData);
-
-switch (result.result) {
-  case "fableOk":
-    console.log("Valid FormSpec:", result.Item);
-    break;
-  case "fableError":
-    console.error("Validation failed:", result.Item);
-    break;
-}
-```
-
-## Quick Start
-
-### 1. Validate Unknown Data
-
-```typescript
-import {
-  Api_validateFormSpec,
-  Api_validateAndConvertFormSpec
-} from '@f1studio/form-spec/Interop/FormSpec.Api';
-
-// Validate JSON data from an API
-async function loadFormSpec(url: string) {
-  const response = await fetch(url);
-  const data = await response.json();
-
-  // Validate to TypeScript-friendly types
-  const result = Api_validateFormSpec()(data);
-
-  if (result.result === "fableOk") {
-    return result.Item; // Fully typed FormSpecTS
-  } else {
-    throw new Error(result.Item);
-  }
-}
-
-// Validate AND convert to F# domain types
-const domainResult = Api_validateAndConvertFormSpec()(data);
-```
-
-### 2. Create Forms with Builders
-
-```typescript
-import {
-  Api_createFormSpec,
-  Api_createTextField,
-  Api_createCheckboxField,
-  Api_createDropdownField,
-  Api_createFieldOption,
-  Builders_formField,
-  Builders_formStep,
-  Builders_formSpec
-} from '@f1studio/form-spec/Interop/FormSpec.Api';
-
-// Create a new empty FormSpec
-const emptySpec = Api_createFormSpec();
-
-// Build a complete form specification
-function createPatientIntakeForm() {
-  // Create field options
-  const genderOptions = [
-    Api_createFieldOption("Male", "male"),
-    Api_createFieldOption("Female", "female"),
-    Api_createFieldOption("Other", "other")
-  ];
-
-  // Create fields
-  const nameField = Builders_formField(
-    "Patient Name",
-    Api_createTextField(null)
-  )
-    .WithOrder(1)
-    .AsOptional()
-    .Build();
-
-  const genderField = Builders_formField(
-    "Gender",
-    Api_createDropdownField(genderOptions)
-  )
-    .WithOrder(2)
-    .Build();
-
-  const consentField = Builders_formField(
-    "I consent to treatment",
-    Api_createCheckboxField(false, null)
-  )
-    .WithOrder(3)
-    .Build();
-
-  // Create form step
-  const demographicsStep = Builders_formStep("Demographics")
-    .WithOrder(1)
-    .AddField(nameField)
-    .AddField(genderField)
-    .AddField(consentField)
-    .Build();
-
-  // Create complete FormSpec
-  const formSpec = Builders_formSpec("Patient Intake Form")
-    .WithCode("INTAKE-001")
-    .WithAbstract("Standard patient intake and consent form")
-    .WithVersion("2.0.0")
-    .AddStep(demographicsStep)
-    .WithTags(["intake", "patient", "consent"])
-    .RequiresReview()
-    .Build();
-
-  return formSpec;
-}
-```
-
-### 3. Field Types
-
-The API supports all standard HTML input types plus specialized medical fields:
-
-```typescript
-import {
-  Api_createTextField,
-  Api_createTextArea,
-  Api_createEmailField,
-  Api_createPasswordField,
-  Api_createNumberField,
-  Api_createDateField,
-  Api_createTimeField,
-  Api_createCheckboxField,
-  Api_createRadioField,
-  Api_createDropdownField,
-  Api_createMultiChoiceField,
-  Api_createMessageField,
-  Types_MessageTypeTS
-} from '@f1studio/form-spec/Interop/FormSpec.Api';
-
-// Text inputs
-const textField = Api_createTextField("default value");
-const emailField = Api_createEmailField(null);
-const numberField = Api_createNumberField("42");
-
-// Date/Time inputs
-const dateField = Api_createDateField("2024-01-01");
-const timeField = Api_createTimeField("14:30");
-
-// Choice inputs
-const options = [
-  Api_createFieldOption("Option 1", "opt1"),
-  Api_createFieldOption("Option 2", "opt2")
-];
-const radioField = Api_createRadioField(options);
-const dropdownField = Api_createDropdownField(options);
-const multiChoiceField = Api_createMultiChoiceField(options);
-
-// Informational
-const messageField = Api_createMessageField(
-  "Important Notice",
-  "Please read carefully before proceeding",
-  Types_MessageTypeTS.Warning
-);
-```
-
-### 4. Field Dependencies
-
-Create conditional field visibility based on other field values:
-
-```typescript
-import {
-  Types_EvaluatorTS,
-  Api_createFieldKey
-} from '@f1studio/form-spec/Interop/FormSpec.Api';
-
-const hasAllergyField = Builders_formField(
-  "Do you have allergies?",
-  Api_createCheckboxField(false, null)
-)
-  .WithOrder(1)
-  .Build();
-
-const allergyDetailsField = Builders_formField(
-  "Please describe your allergies",
-  Api_createTextField(null)
-)
-  .WithOrder(2)
-  .WithDependency({
-    FieldKey: hasAllergyField.FieldKey,
-    FieldValue: "true",
-    Evaluator: Types_EvaluatorTS.Equals
-  })
-  .Build();
-```
-
-### 5. Serialization
-
-```typescript
-import {
-  Api_serializeFormSpec,
-  Api_deserializeFormSpec
-} from '@f1studio/form-spec/Interop/FormSpec.Api';
-
-// Convert FormSpec to JSON string
-const formSpec = createPatientIntakeForm();
-const json = Api_serializeFormSpec(formSpec);
-localStorage.setItem('formSpec', json);
-
-// Deserialize from JSON string
-const savedJson = localStorage.getItem('formSpec');
-const result = Api_deserializeFormSpec(savedJson);
-
-if (result.result === "fableOk") {
-  const restoredSpec = result.Item;
-  console.log("Loaded form:", restoredSpec.Title);
-}
-```
-
-### 6. Query and Utility Functions
-
-```typescript
-import {
-  Api_getFieldKeys,
-  Api_findFieldByKey,
-  Api_getFieldsByType,
-  Api_isValidFormSpec,
-  Api_getFormSpecSummary
-} from '@f1studio/form-spec/Interop/FormSpec.Api';
-
-const formSpec = createPatientIntakeForm();
-
-// Get all field keys
-const fieldKeys = Api_getFieldKeys(formSpec);
-console.log(`Form has ${fieldKeys.length} fields`);
-
-// Find a specific field
-const field = Api_findFieldByKey(formSpec, fieldKeys[0]);
-if (field) {
-  console.log("Found field:", field.Label);
-}
-
-// Get all text fields
-const textFields = Api_getFieldsByType(formSpec, "Text");
-console.log(`Found ${textFields.length} text fields`);
-
-// Validate structure
-if (Api_isValidFormSpec(formSpec)) {
-  console.log("FormSpec is valid");
-}
-
-// Get summary information
-const summary = Api_getFormSpecSummary(formSpec);
-console.log(summary);
-// Output: { Id, Title, Version, StepCount, FieldCount, RequiresReview, RequiresApproval }
-```
-
-### 7. Scoring System
-
-Add scoring ranges for assessments and evaluations:
-
-```typescript
-import {
-  Types_ScoreColorTS,
-  Api_createScoreRange
-} from '@f1studio/form-spec/Interop/FormSpec.Api';
-
-const scoreRanges = [
-  {
-    Id: "550e8400-e29b-41d4-a716-446655440001",
-    Min: 0,
-    Max: 10,
-    Label: "Low Risk",
-    Tag: Types_ScoreColorTS.Success
-  },
-  {
-    Id: "550e8400-e29b-41d4-a716-446655440002",
-    Min: 11,
-    Max: 20,
-    Label: "Medium Risk",
-    Tag: Types_ScoreColorTS.Warning
-  },
-  {
-    Id: "550e8400-e29b-41d4-a716-446655440003",
-    Min: 21,
-    Max: 30,
-    Label: "High Risk",
-    Tag: Types_ScoreColorTS.Danger
-  }
-];
-
-const formWithScore = Builders_formSpec("Risk Assessment")
-  .WithScore({
-    MaxScore: 30,
-    ScoreRanges: scoreRanges
-  })
-  .Build();
-```
-
-### 8. Matrix/Likert Scale Fields
-
-Create matrix questions for surveys and assessments:
-
-```typescript
-const satisfactionItems = [
-  Api_createFieldOption("Wait time", "wait_time"),
-  Api_createFieldOption("Staff friendliness", "staff"),
-  Api_createFieldOption("Cleanliness", "clean"),
-];
-
-const ratingScale = [
-  Api_createFieldOption("Very Dissatisfied", "1"),
-  Api_createFieldOption("Dissatisfied", "2"),
-  Api_createFieldOption("Neutral", "3"),
-  Api_createFieldOption("Satisfied", "4"),
-  Api_createFieldOption("Very Satisfied", "5"),
-];
-
-const matrixField = Builders_formField(
-  "Please rate your experience",
-  {
-    Type: "Matrix",
-    MatrixInfo: {
-      Items: satisfactionItems,
-      Options: ratingScale
-    },
-    // ... other properties set to null
-  }
-).Build();
-```
-
-## Advanced Usage
-
-### Type Guards and Validation
-
-```typescript
-import { FormSpecTS } from '@f1studio/form-spec/Interop/FormSpec.Api';
-
-// Type guard for FormSpec
-function isFormSpec(obj: any): obj is FormSpecTS {
-  const result = Api_validateFormSpec()(obj);
-  return result.result === "fableOk";
-}
-
-// Use in your code
-function processForm(data: unknown) {
-  if (isFormSpec(data)) {
-    // data is now typed as FormSpecTS
-    console.log(data.Title);
-    data.Steps.forEach(step => {
-      console.log(step.StepLabel);
-    });
-  }
-}
-```
-
-### Batch Validation
-
-```typescript
-import { Api_validateFormSpecs } from '@f1studio/form-spec/Interop/FormSpec.Api';
-
-async function validateMultipleForms(urls: string[]) {
-  const responses = await Promise.all(
-    urls.map(url => fetch(url).then(r => r.json()))
-  );
-
-  const result = Api_validateFormSpecs(responses);
-
-  if (result.result === "fableOk") {
-    return result.Item; // FormSpecTS[]
-  } else {
-    throw new Error(`Validation failed: ${result.Item}`);
-  }
-}
-```
-
-### Working with GUIDs
-
-All keys in the system use GUIDs wrapped in typed objects:
-
-```typescript
-import {
-  Api_createFieldKey,
-  Api_createStateKey,
-  Api_createTransitionKey
-} from '@f1studio/form-spec/Interop/FormSpec.Api';
-
-// Generate new keys
-const fieldKey = Api_createFieldKey();      // { Value: "uuid..." }
-const stateKey = Api_createStateKey();      // { Value: "uuid..." }
-const transitionKey = Api_createTransitionKey(); // { Value: "uuid..." }
-
-// Keys are automatically generated when using builders
-const field = Builders_formField("Name", Api_createTextField(null))
-  .Build();
-console.log(field.FieldKey.Value); // UUID string
-```
-
-## React Integration Example
-
-```typescript
-import React, { useState, useEffect } from 'react';
-import {
-  FormSpecTS,
-  Api_validateFormSpec,
-  Api_getFieldsByType
-} from '@f1studio/form-spec/Interop/FormSpec.Api';
-
-function FormRenderer({ formData }: { formData: unknown }) {
-  const [formSpec, setFormSpec] = useState<FormSpecTS | null>(null);
-  const [error, setError] = useState<string | null>(null);
-
-  useEffect(() => {
-    const result = Api_validateFormSpec()(formData);
-
-    if (result.result === "fableOk") {
-      setFormSpec(result.Item);
-      setError(null);
-    } else {
-      setError(result.Item);
-      setFormSpec(null);
-    }
-  }, [formData]);
-
-  if (error) {
-    return <div className="error">Invalid form: {error}</div>;
-  }
-
-  if (!formSpec) {
-    return <div>Loading...</div>;
-  }
-
-  return (
-    <div className="form-renderer">
-      <h1>{formSpec.Title}</h1>
-      <p>{formSpec.Abstract}</p>
-
-      {formSpec.Steps.map((step, stepIdx) => (
-        <div key={stepIdx} className="form-step">
-          <h2>{step.StepLabel}</h2>
-          {step.Fields.map((field, fieldIdx) => (
-            <div key={field.FieldKey.Value} className="form-field">
-              <label>{field.Label}</label>
-              {/* Render appropriate input based on field.FieldType.Type */}
-            </div>
-          ))}
-        </div>
-      ))}
-    </div>
-  );
-}
-```
-
-## Type Definitions
-
-### Core Types
-
-```typescript
-interface FormSpecTS {
-  Id: string;
-  Code?: string;
-  Title: string;
-  Abstract: string;
-  Version: string;
-  FormSpecVersion: string;
-  Steps: FormStepTS[];
-  CategoryTags: string[];
-  Score?: ScoreTS;
-  AssociatedCodes: string[];
-  RequiresReview: boolean;
-  RequiresReviewAndApproval: boolean;
-  ClinicalPathway?: ClinicalPathwaySpecTS;
-}
-
-interface FormStepTS {
-  StepOrder: number;
-  StepLabel: string;
-  Fields: FormFieldTS[];
-}
-
-interface FormFieldTS {
-  FieldOrder: number;
-  FieldKey: FieldKeyTS;
-  Label: string;
-  DependsOn?: DependsOnTS;
-  IsOptional: boolean;
-  IsDeprecated: boolean;
-  FieldType: FieldTypeTS;
-}
-
-interface FieldTypeTS {
-  Type: string; // "Text", "Checkbox", "Radio", etc.
-  TextInfo?: TextInfoTS;
-  BooleanInfo?: BooleanInfoTS;
-  SingleChoiceInfo?: SingleChoiceInfoTS;
-  MultiChoiceInfo?: MultiChoiceInfoTS;
-  MessageInfo?: MessageInfoTS;
-  MatrixInfo?: MatrixInfoTS;
-  SignatureInfo?: SignatureInfoTS;
-  PluginConfig?: PluginFieldConfigTS;
-}
-```
-
-## Best Practices
-
-1. **Always Validate External Data**: Never trust data from APIs, files, or user input without validation
-2. **Use Builders for Type Safety**: Builders ensure all required fields are set correctly
-3. **Handle Both Result Cases**: Always handle both `fableOk` and `fableError` cases
-4. **Leverage TypeScript Types**: Import type definitions for IntelliSense and compile-time checking
-5. **Store GUIDs as Strings**: When persisting to databases, use the `Value` property of key types
-
-## Migration from Legacy Forms
-
-If you have existing form data in a different format:
-
-```typescript
-function migrateOldForm(oldForm: any): FormSpecTS {
-  const builder = Builders_formSpec(oldForm.title || "Untitled Form")
-    .WithVersion(oldForm.version || "1.0.0");
-
-  // Map old fields to new structure
-  oldForm.questions?.forEach((q: any, idx: number) => {
-    const field = Builders_formField(
-      q.text,
-      mapOldFieldType(q.type, q.options)
-    )
-      .WithOrder(idx + 1)
-      .Build();
-
-    // Add to step...
-  });
-
-  return builder.Build();
-}
-
-function mapOldFieldType(type: string, options?: any[]): FieldTypeTS {
-  switch(type) {
-    case 'text': return Api_createTextField(null);
-    case 'select': return Api_createDropdownField(
-      options?.map(o => Api_createFieldOption(o.label, o.value)) || []
-    );
-    // ... map other types
-    default: return Api_createTextField(null);
-  }
-}
-```
-
-## Troubleshooting
-
-### Common Issues
-
-**Issue**: Validation fails with "Invalid GUID for FieldKey"
-**Solution**: Ensure you're using the key creation functions or builders which generate valid GUIDs
-
-**Issue**: TypeScript can't find types
-**Solution**: Import from the specific path: `@f1studio/form-spec/Interop/FormSpec.Api`
-
-**Issue**: FableResult is not being recognized in switch statements
-**Solution**: Check the discriminator property is exactly `result` (lowercase)
-
-## API Reference
-
-### Validation Functions
-- `Api_validateFormSpec(input: any): FableResult<FormSpecTS, string>` - Validate unknown data to FormSpecTS
-- `Api_validateAndConvertFormSpec(input: any): FableResult<FormSpec, string>` - Validate and convert to F# domain type
-- `Api_validateFormField(input: any): FableResult<FormFieldTS, string>` - Validate a single field
-- `Api_validateFormStep(input: any): FableResult<FormStepTS, string>` - Validate a form step
-- `Api_validateFieldType(input: any): FableResult<FieldTypeTS, string>` - Validate a field type
-
-### Builder Functions
-- `Api_createFormSpec(): FormSpecTS` - Create empty FormSpec
-- `Api_createFieldKey(): FieldKeyTS` - Generate new field key
-- `Api_createFieldOption(description: string, value: string): FieldOptionTS` - Create field option
-- `Api_createTextField(value: string | null): FieldTypeTS` - Create text field
-- `Api_createCheckboxField(defaultValue: boolean | null, selection: boolean | null): FieldTypeTS` - Create checkbox
-- `Api_createRadioField(options: FieldOptionTS[]): FieldTypeTS` - Create radio button group
-- `Api_createDropdownField(options: FieldOptionTS[]): FieldTypeTS` - Create dropdown
-
-### Serialization Functions
-- `Api_serializeFormSpec(spec: FormSpecTS): string` - Convert to JSON string
-- `Api_deserializeFormSpec(json: string): FableResult<FormSpecTS, string>` - Parse from JSON
-
-### Query Functions
-- `Api_getFieldKeys(spec: FormSpecTS): FieldKeyTS[]` - Get all field keys
-- `Api_findFieldByKey(spec: FormSpecTS, key: FieldKeyTS): FormFieldTS | undefined` - Find field by key
-- `Api_getFieldsByType(spec: FormSpecTS, type: string): FormFieldTS[]` - Get fields of specific type
-- `Api_isValidFormSpec(spec: FormSpecTS): boolean` - Check if spec is valid
-- `Api_getFormSpecSummary(spec: FormSpecTS): object` - Get spec summary
-
-## Support
-
-For issues, questions, or contributions:
-- GitHub: https://github.com/f1-studio/f1-monorepo
-- Documentation: https://f1studio.ai/docs
-
-## License
-
+# FormSpec TypeScript API Documentation
+
+## 🚀 F# to TypeScript Interop for Form Specifications
+
+The FormSpec TypeScript API provides a type-safe, validated bridge between F# domain models and TypeScript applications. Built with Fable and Thoth.Json, it enables seamless form specification management across the F#/TypeScript boundary.
+
+## Installation
+
+```bash
+# From Verdaccio local registry
+npm install @f1studio/form-spec@5.0.0-alpha.13 --registry http://localhost:4873
+# or
+pnpm add @f1studio/form-spec@5.0.0-alpha.13 --registry http://localhost:4873
+# or
+yarn add @f1studio/form-spec@5.0.0-alpha.13 --registry http://localhost:4873
+```
+
+## Core Concepts
+
+### FableResult Type
+All validation functions return a `FableResult<T, E>` - a TypeScript-friendly tagged union:
+
+```typescript
+type FableResult<T, E> =
+  | { result: "fableOk"; Item: T }
+  | { result: "fableError"; Item: E }
+```
+
+This enables safe pattern matching in TypeScript:
+
+```typescript
+const result = validateFormSpec(unknownData);
+
+switch (result.result) {
+  case "fableOk":
+    console.log("Valid FormSpec:", result.Item);
+    break;
+  case "fableError":
+    console.error("Validation failed:", result.Item);
+    break;
+}
+```
+
+## Quick Start
+
+### 1. Validate Unknown Data
+
+```typescript
+import {
+  Api_validateFormSpec,
+  Api_validateAndConvertFormSpec
+} from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+// Validate JSON data from an API
+async function loadFormSpec(url: string) {
+  const response = await fetch(url);
+  const data = await response.json();
+
+  // Validate to TypeScript-friendly types
+  const result = Api_validateFormSpec()(data);
+
+  if (result.result === "fableOk") {
+    return result.Item; // Fully typed FormSpecTS
+  } else {
+    throw new Error(result.Item);
+  }
+}
+
+// Validate AND convert to F# domain types
+const domainResult = Api_validateAndConvertFormSpec()(data);
+```
+
+### 2. Create Forms with Builders
+
+```typescript
+import {
+  Api_createFormSpec,
+  Api_createTextField,
+  Api_createCheckboxField,
+  Api_createDropdownField,
+  Api_createFieldOption,
+  Builders_formField,
+  Builders_formStep,
+  Builders_formSpec
+} from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+// Create a new empty FormSpec
+const emptySpec = Api_createFormSpec();
+
+// Build a complete form specification
+function createPatientIntakeForm() {
+  // Create field options
+  const genderOptions = [
+    Api_createFieldOption("Male", "male"),
+    Api_createFieldOption("Female", "female"),
+    Api_createFieldOption("Other", "other")
+  ];
+
+  // Create fields
+  const nameField = Builders_formField(
+    "Patient Name",
+    Api_createTextField(null)
+  )
+    .WithOrder(1)
+    .AsOptional()
+    .Build();
+
+  const genderField = Builders_formField(
+    "Gender",
+    Api_createDropdownField(genderOptions)
+  )
+    .WithOrder(2)
+    .Build();
+
+  const consentField = Builders_formField(
+    "I consent to treatment",
+    Api_createCheckboxField(false, null)
+  )
+    .WithOrder(3)
+    .Build();
+
+  // Create form step
+  const demographicsStep = Builders_formStep("Demographics")
+    .WithOrder(1)
+    .AddField(nameField)
+    .AddField(genderField)
+    .AddField(consentField)
+    .Build();
+
+  // Create complete FormSpec
+  const formSpec = Builders_formSpec("Patient Intake Form")
+    .WithCode("INTAKE-001")
+    .WithAbstract("Standard patient intake and consent form")
+    .WithVersion("2.0.0")
+    .AddStep(demographicsStep)
+    .WithTags(["intake", "patient", "consent"])
+    .RequiresReview()
+    .Build();
+
+  return formSpec;
+}
+```
+
+### 3. Field Types
+
+The API supports all standard HTML input types plus specialized medical fields:
+
+```typescript
+import {
+  Api_createTextField,
+  Api_createTextArea,
+  Api_createEmailField,
+  Api_createPasswordField,
+  Api_createNumberField,
+  Api_createDateField,
+  Api_createTimeField,
+  Api_createCheckboxField,
+  Api_createRadioField,
+  Api_createDropdownField,
+  Api_createMultiChoiceField,
+  Api_createMessageField,
+  Types_MessageTypeTS
+} from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+// Text inputs
+const textField = Api_createTextField("default value");
+const emailField = Api_createEmailField(null);
+const numberField = Api_createNumberField("42");
+
+// Date/Time inputs
+const dateField = Api_createDateField("2024-01-01");
+const timeField = Api_createTimeField("14:30");
+
+// Choice inputs
+const options = [
+  Api_createFieldOption("Option 1", "opt1"),
+  Api_createFieldOption("Option 2", "opt2")
+];
+const radioField = Api_createRadioField(options);
+const dropdownField = Api_createDropdownField(options);
+const multiChoiceField = Api_createMultiChoiceField(options);
+
+// Informational
+const messageField = Api_createMessageField(
+  "Important Notice",
+  "Please read carefully before proceeding",
+  Types_MessageTypeTS.Warning
+);
+```
+
+### 4. Field Dependencies
+
+Create conditional field visibility based on other field values:
+
+```typescript
+import {
+  Types_EvaluatorTS,
+  Api_createFieldKey
+} from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+const hasAllergyField = Builders_formField(
+  "Do you have allergies?",
+  Api_createCheckboxField(false, null)
+)
+  .WithOrder(1)
+  .Build();
+
+const allergyDetailsField = Builders_formField(
+  "Please describe your allergies",
+  Api_createTextField(null)
+)
+  .WithOrder(2)
+  .WithDependency({
+    FieldKey: hasAllergyField.FieldKey,
+    FieldValue: "true",
+    Evaluator: Types_EvaluatorTS.Equals
+  })
+  .Build();
+```
+
+### 5. Serialization
+
+```typescript
+import {
+  Api_serializeFormSpec,
+  Api_deserializeFormSpec
+} from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+// Convert FormSpec to JSON string
+const formSpec = createPatientIntakeForm();
+const json = Api_serializeFormSpec(formSpec);
+localStorage.setItem('formSpec', json);
+
+// Deserialize from JSON string
+const savedJson = localStorage.getItem('formSpec');
+const result = Api_deserializeFormSpec(savedJson);
+
+if (result.result === "fableOk") {
+  const restoredSpec = result.Item;
+  console.log("Loaded form:", restoredSpec.Title);
+}
+```
+
+### 6. Query and Utility Functions
+
+```typescript
+import {
+  Api_getFieldKeys,
+  Api_findFieldByKey,
+  Api_getFieldsByType,
+  Api_isValidFormSpec,
+  Api_getFormSpecSummary
+} from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+const formSpec = createPatientIntakeForm();
+
+// Get all field keys
+const fieldKeys = Api_getFieldKeys(formSpec);
+console.log(`Form has ${fieldKeys.length} fields`);
+
+// Find a specific field
+const field = Api_findFieldByKey(formSpec, fieldKeys[0]);
+if (field) {
+  console.log("Found field:", field.Label);
+}
+
+// Get all text fields
+const textFields = Api_getFieldsByType(formSpec, "Text");
+console.log(`Found ${textFields.length} text fields`);
+
+// Validate structure
+if (Api_isValidFormSpec(formSpec)) {
+  console.log("FormSpec is valid");
+}
+
+// Get summary information
+const summary = Api_getFormSpecSummary(formSpec);
+console.log(summary);
+// Output: { Id, Title, Version, StepCount, FieldCount, RequiresReview, RequiresApproval }
+```
+
+### 7. Scoring System
+
+Add scoring ranges for assessments and evaluations:
+
+```typescript
+import {
+  Types_ScoreColorTS,
+  Api_createScoreRange
+} from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+const scoreRanges = [
+  {
+    Id: "550e8400-e29b-41d4-a716-446655440001",
+    Min: 0,
+    Max: 10,
+    Label: "Low Risk",
+    Tag: Types_ScoreColorTS.Success
+  },
+  {
+    Id: "550e8400-e29b-41d4-a716-446655440002",
+    Min: 11,
+    Max: 20,
+    Label: "Medium Risk",
+    Tag: Types_ScoreColorTS.Warning
+  },
+  {
+    Id: "550e8400-e29b-41d4-a716-446655440003",
+    Min: 21,
+    Max: 30,
+    Label: "High Risk",
+    Tag: Types_ScoreColorTS.Danger
+  }
+];
+
+const formWithScore = Builders_formSpec("Risk Assessment")
+  .WithScore({
+    MaxScore: 30,
+    ScoreRanges: scoreRanges
+  })
+  .Build();
+```
+
+### 8. Matrix/Likert Scale Fields
+
+Create matrix questions for surveys and assessments:
+
+```typescript
+const satisfactionItems = [
+  Api_createFieldOption("Wait time", "wait_time"),
+  Api_createFieldOption("Staff friendliness", "staff"),
+  Api_createFieldOption("Cleanliness", "clean"),
+];
+
+const ratingScale = [
+  Api_createFieldOption("Very Dissatisfied", "1"),
+  Api_createFieldOption("Dissatisfied", "2"),
+  Api_createFieldOption("Neutral", "3"),
+  Api_createFieldOption("Satisfied", "4"),
+  Api_createFieldOption("Very Satisfied", "5"),
+];
+
+const matrixField = Builders_formField(
+  "Please rate your experience",
+  {
+    Type: "Matrix",
+    MatrixInfo: {
+      Items: satisfactionItems,
+      Options: ratingScale
+    },
+    // ... other properties set to null
+  }
+).Build();
+```
+
+## Advanced Usage
+
+### Type Guards and Validation
+
+```typescript
+import { FormSpecTS } from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+// Type guard for FormSpec
+function isFormSpec(obj: any): obj is FormSpecTS {
+  const result = Api_validateFormSpec()(obj);
+  return result.result === "fableOk";
+}
+
+// Use in your code
+function processForm(data: unknown) {
+  if (isFormSpec(data)) {
+    // data is now typed as FormSpecTS
+    console.log(data.Title);
+    data.Steps.forEach(step => {
+      console.log(step.StepLabel);
+    });
+  }
+}
+```
+
+### Batch Validation
+
+```typescript
+import { Api_validateFormSpecs } from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+async function validateMultipleForms(urls: string[]) {
+  const responses = await Promise.all(
+    urls.map(url => fetch(url).then(r => r.json()))
+  );
+
+  const result = Api_validateFormSpecs(responses);
+
+  if (result.result === "fableOk") {
+    return result.Item; // FormSpecTS[]
+  } else {
+    throw new Error(`Validation failed: ${result.Item}`);
+  }
+}
+```
+
+### Working with GUIDs
+
+All keys in the system use GUIDs wrapped in typed objects:
+
+```typescript
+import {
+  Api_createFieldKey,
+  Api_createStateKey,
+  Api_createTransitionKey
+} from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+// Generate new keys
+const fieldKey = Api_createFieldKey();      // { Value: "uuid..." }
+const stateKey = Api_createStateKey();      // { Value: "uuid..." }
+const transitionKey = Api_createTransitionKey(); // { Value: "uuid..." }
+
+// Keys are automatically generated when using builders
+const field = Builders_formField("Name", Api_createTextField(null))
+  .Build();
+console.log(field.FieldKey.Value); // UUID string
+```
+
+## React Integration Example
+
+```typescript
+import React, { useState, useEffect } from 'react';
+import {
+  FormSpecTS,
+  Api_validateFormSpec,
+  Api_getFieldsByType
+} from '@f1studio/form-spec/Interop/FormSpec.Api';
+
+function FormRenderer({ formData }: { formData: unknown }) {
+  const [formSpec, setFormSpec] = useState<FormSpecTS | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    const result = Api_validateFormSpec()(formData);
+
+    if (result.result === "fableOk") {
+      setFormSpec(result.Item);
+      setError(null);
+    } else {
+      setError(result.Item);
+      setFormSpec(null);
+    }
+  }, [formData]);
+
+  if (error) {
+    return <div className="error">Invalid form: {error}</div>;
+  }
+
+  if (!formSpec) {
+    return <div>Loading...</div>;
+  }
+
+  return (
+    <div className="form-renderer">
+      <h1>{formSpec.Title}</h1>
+      <p>{formSpec.Abstract}</p>
+
+      {formSpec.Steps.map((step, stepIdx) => (
+        <div key={stepIdx} className="form-step">
+          <h2>{step.StepLabel}</h2>
+          {step.Fields.map((field, fieldIdx) => (
+            <div key={field.FieldKey.Value} className="form-field">
+              <label>{field.Label}</label>
+              {/* Render appropriate input based on field.FieldType.Type */}
+            </div>
+          ))}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Type Definitions
+
+### Core Types
+
+```typescript
+interface FormSpecTS {
+  Id: string;
+  Code?: string;
+  Title: string;
+  Abstract: string;
+  Version: string;
+  FormSpecVersion: string;
+  Steps: FormStepTS[];
+  CategoryTags: string[];
+  Score?: ScoreTS;
+  AssociatedCodes: string[];
+  RequiresReview: boolean;
+  RequiresReviewAndApproval: boolean;
+  ClinicalPathway?: ClinicalPathwaySpecTS;
+}
+
+interface FormStepTS {
+  StepOrder: number;
+  StepLabel: string;
+  Fields: FormFieldTS[];
+}
+
+interface FormFieldTS {
+  FieldOrder: number;
+  FieldKey: FieldKeyTS;
+  Label: string;
+  DependsOn?: DependsOnTS;
+  IsOptional: boolean;
+  IsDeprecated: boolean;
+  FieldType: FieldTypeTS;
+}
+
+interface FieldTypeTS {
+  Type: string; // "Text", "Checkbox", "Radio", etc.
+  TextInfo?: TextInfoTS;
+  BooleanInfo?: BooleanInfoTS;
+  SingleChoiceInfo?: SingleChoiceInfoTS;
+  MultiChoiceInfo?: MultiChoiceInfoTS;
+  MessageInfo?: MessageInfoTS;
+  MatrixInfo?: MatrixInfoTS;
+  SignatureInfo?: SignatureInfoTS;
+  PluginConfig?: PluginFieldConfigTS;
+}
+```
+
+## Best Practices
+
+1. **Always Validate External Data**: Never trust data from APIs, files, or user input without validation
+2. **Use Builders for Type Safety**: Builders ensure all required fields are set correctly
+3. **Handle Both Result Cases**: Always handle both `fableOk` and `fableError` cases
+4. **Leverage TypeScript Types**: Import type definitions for IntelliSense and compile-time checking
+5. **Store GUIDs as Strings**: When persisting to databases, use the `Value` property of key types
+
+## Migration from Legacy Forms
+
+If you have existing form data in a different format:
+
+```typescript
+function migrateOldForm(oldForm: any): FormSpecTS {
+  const builder = Builders_formSpec(oldForm.title || "Untitled Form")
+    .WithVersion(oldForm.version || "1.0.0");
+
+  // Map old fields to new structure
+  oldForm.questions?.forEach((q: any, idx: number) => {
+    const field = Builders_formField(
+      q.text,
+      mapOldFieldType(q.type, q.options)
+    )
+      .WithOrder(idx + 1)
+      .Build();
+
+    // Add to step...
+  });
+
+  return builder.Build();
+}
+
+function mapOldFieldType(type: string, options?: any[]): FieldTypeTS {
+  switch(type) {
+    case 'text': return Api_createTextField(null);
+    case 'select': return Api_createDropdownField(
+      options?.map(o => Api_createFieldOption(o.label, o.value)) || []
+    );
+    // ... map other types
+    default: return Api_createTextField(null);
+  }
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: Validation fails with "Invalid GUID for FieldKey"
+**Solution**: Ensure you're using the key creation functions or builders which generate valid GUIDs
+
+**Issue**: TypeScript can't find types
+**Solution**: Import from the specific path: `@f1studio/form-spec/Interop/FormSpec.Api`
+
+**Issue**: FableResult is not being recognized in switch statements
+**Solution**: Check the discriminator property is exactly `result` (lowercase)
+
+## API Reference
+
+### Validation Functions
+- `Api_validateFormSpec(input: any): FableResult<FormSpecTS, string>` - Validate unknown data to FormSpecTS
+- `Api_validateAndConvertFormSpec(input: any): FableResult<FormSpec, string>` - Validate and convert to F# domain type
+- `Api_validateFormField(input: any): FableResult<FormFieldTS, string>` - Validate a single field
+- `Api_validateFormStep(input: any): FableResult<FormStepTS, string>` - Validate a form step
+- `Api_validateFieldType(input: any): FableResult<FieldTypeTS, string>` - Validate a field type
+
+### Builder Functions
+- `Api_createFormSpec(): FormSpecTS` - Create empty FormSpec
+- `Api_createFieldKey(): FieldKeyTS` - Generate new field key
+- `Api_createFieldOption(description: string, value: string): FieldOptionTS` - Create field option
+- `Api_createTextField(value: string | null): FieldTypeTS` - Create text field
+- `Api_createCheckboxField(defaultValue: boolean | null, selection: boolean | null): FieldTypeTS` - Create checkbox
+- `Api_createRadioField(options: FieldOptionTS[]): FieldTypeTS` - Create radio button group
+- `Api_createDropdownField(options: FieldOptionTS[]): FieldTypeTS` - Create dropdown
+
+### Serialization Functions
+- `Api_serializeFormSpec(spec: FormSpecTS): string` - Convert to JSON string
+- `Api_deserializeFormSpec(json: string): FableResult<FormSpecTS, string>` - Parse from JSON
+
+### Query Functions
+- `Api_getFieldKeys(spec: FormSpecTS): FieldKeyTS[]` - Get all field keys
+- `Api_findFieldByKey(spec: FormSpecTS, key: FieldKeyTS): FormFieldTS | undefined` - Find field by key
+- `Api_getFieldsByType(spec: FormSpecTS, type: string): FormFieldTS[]` - Get fields of specific type
+- `Api_isValidFormSpec(spec: FormSpecTS): boolean` - Check if spec is valid
+- `Api_getFormSpecSummary(spec: FormSpecTS): object` - Get spec summary
+
+## Support
+
+For issues, questions, or contributions:
+- GitHub: https://github.com/f1-studio/f1-monorepo
+- Documentation: https://f1studio.ai/docs
+
+## License
+
 MIT © F1 Studio