Requirements

{
  "object": "requirements",
  "jurisdiction": "SG",
  "type": "PRIVATE_LIMITED_COMPANY",
  "version": "2026-09-01",
  "blocks": [
    {
      "key": "company",
      "title": "Company details",
      "fields": [
        {
          "key": "companyNameOptions",
          "kind": "collection",
          "label": "Company name options, in order of preference",
          "required": true,
          "cardinality": { "exact": 3 },
          "constraints": { "uniqueItems": true },
          "item": { "kind": "scalar", "input": { "type": "text", "placeholder": "Northwind Asia Pte. Ltd." } }
        },
        {
          "key": "financialYearEnd",
          "kind": "scalar",
          "label": "Financial year end (MM-DD)",
          "required": true,
          "input": { "type": "text", "pattern": "^(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$" }
        }
      ]
    },
    {
      "key": "registeredOffice",
      "title": "Registered office",
      "fields": [
        {
          "key": "registeredOfficeAddressSource",
          "kind": "scalar",
          "label": "Registered office address",
          "required": true,
          "input": {
            "type": "select",
            "options": [
              { "value": "getstartedService", "label": "Use the GetStarted registered office service" },
              { "value": "customerProvidedLocation", "label": "Use an address I provide" }
            ]
          }
        },
        {
          "key": "registeredOfficeAddressLocation",
          "kind": "resource",
          "label": "Registered office location",
          "resourceType": "LOCATION",
          "modes": ["existingResource", "inlineData"],
          "required": { "when": { "fieldKey": "registeredOfficeAddressSource", "equals": "customerProvidedLocation" } },
          "appliesWhen": { "fieldKey": "registeredOfficeAddressSource", "equals": "customerProvidedLocation" },
          "dataFields": [
            { "key": "line1", "kind": "scalar", "label": "Address line 1", "required": true, "input": { "type": "text" } },
            { "key": "city", "kind": "scalar", "label": "City", "required": true, "input": { "type": "text" } },
            { "key": "postalCode", "kind": "scalar", "label": "Postal code", "required": true, "input": { "type": "text" } },
            { "key": "country", "kind": "scalar", "label": "Country", "required": true, "input": { "type": "country" } }
          ]
        }
      ]
    }
  ],
  "participantRequirements": [
    {
      "role": "DIRECTOR",
      "cardinality": { "min": 1, "max": 12 },
      "allowedParticipantTypes": ["INDIVIDUAL"],
      "resourceFieldsByParticipantType": {
        "INDIVIDUAL": [
          { "key": "firstName", "kind": "scalar", "required": true, "input": { "type": "text" } },
          { "key": "dateOfBirth", "kind": "scalar", "required": true, "input": { "type": "date" } },
          { "key": "nationality", "kind": "scalar", "required": true, "input": { "type": "country" } }
        ]
      }
    },
    {
      "role": "SHAREHOLDER",
      "cardinality": { "min": 1, "max": 50 },
      "allowedParticipantTypes": ["INDIVIDUAL", "CORPORATE"],
      "constraints": { "sumEquals": { "field": "ownershipPercentage", "value": 100 } },
      "resourceFieldsByParticipantType": {
        "CORPORATE": [
          { "key": "legalName", "kind": "scalar", "required": true, "input": { "type": "text" } },
          { "key": "countryOfIncorporation", "kind": "scalar", "required": true, "input": { "type": "country" } },
          { "key": "registrationNumber", "kind": "scalar", "required": true, "input": { "type": "text" } }
        ]
      }
    }
  ],
  "documentRequirements": [
    { "role": "DIRECTOR", "participantType": "INDIVIDUAL", "documentKind": "PASSPORT_SCAN", "required": true },
    { "role": "DIRECTOR", "participantType": "INDIVIDUAL", "documentKind": "PROOF_OF_ADDRESS", "required": true },
    { "role": "SHAREHOLDER", "participantType": "CORPORATE", "documentKind": "CERTIFICATE_OF_INCORPORATION", "required": true }
  ]
}

{
  "requirements": {
    "companyNameOptions": ["Northwind Asia Pte. Ltd.", "Northwind Labs Asia Pte. Ltd.", "Northwind Pacific Pte. Ltd."],
    "financialYearEnd": "12-31",
    "registeredOfficeAddressSource": "getstartedService"
  }
}

{
  "requirements": {
    "shareCapital": { "amount": 10000, "currency": "SGD" }
  }
}

{
  "key": "shareClasses",
  "kind": "collection",
  "label": "Share classes",
  "required": true,
  "cardinality": { "min": 1, "max": 5 },
  "constraints": { "uniqueItems": true, "sumEquals": { "field": "percentageOfCapital", "value": 100 } },
  "item": {
    "kind": "object",
    "fields": [
      { "key": "name", "kind": "scalar", "label": "Class name", "required": true, "input": { "type": "text" } },
      { "key": "percentageOfCapital", "kind": "scalar", "label": "Share of capital", "required": true, "input": { "type": "percent" } }
    ]
  }
}

{
  "requirements": {
    "shareClasses": [
      { "name": "Ordinary", "percentageOfCapital": 70 },
      { "name": "Preference", "percentageOfCapital": 30 }
    ]
  }
}

{
  "requirements": {
    "companyNameOptions": ["Northwind Asia Pte. Ltd.", "Northwind Labs Asia Pte. Ltd.", "Northwind Pacific Pte. Ltd."]
  }
}

{
  "requirements": {
    "registeredOfficeAddressSource": "getstartedService"
  }
}

{
  "requirements": {
    "registeredOfficeAddressSource": "customerProvidedLocation",
    "registeredOfficeAddressLocation": {
      "mode": "inlineData",
      "data": {
        "line1": "18 Robinson Road",
        "line2": "#12-01",
        "city": "Singapore",
        "postalCode": "048547",
        "country": "SG"
      }
    }
  }
}

curl https://api.getstarted.ae/v1/customers/cus_01J9ZK4R7Q2M8X/persons \
  -H "Authorization: Bearer gs_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Maya",
    "lastName": "Okafor",
    "dateOfBirth": "1989-04-17",
    "nationality": "GB",
    "email": "maya@northwindlabs.com",
    "phone": "+447700900123",
    "residentialAddress": {
      "line1": "42 Elm Street",
      "city": "London",
      "postalCode": "N1 7GU",
      "country": "GB"
    }
  }'

curl https://api.getstarted.ae/v1/incorporations/inc_01J9ZK7C3VYB5N/participants \
  -H "Authorization: Bearer gs_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "participantType": "INDIVIDUAL",
    "resource": { "resourceType": "PERSON", "resourceId": "per_01J9ZKA1M4HD2T" },
    "roles": [{ "role": "DIRECTOR" }]
  }'

curl -X PUT https://api.getstarted.ae/v1/incorporations/inc_01J9ZK7C3VYB5N/participants/par_01J9ZKE7LB2H6J/documents/PASSPORT_SCAN \
  -H "Authorization: Bearer gs_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "fileId": "file_01J9ZKG1DV4K8N" }'

export type Primitive = string | number | boolean | null;

export type Condition = { fieldKey: string; equals: Primitive };

export type Requirement = boolean | { when: Condition };

export type Cardinality = { exact?: number; min?: number; max?: number };

export type Input = {
  type: "text" | "textarea" | "email" | "phone" | "date" | "country" | "select" | "number" | "percent";
  placeholder?: string;
  pattern?: string;
  min?: number;
  max?: number;
  options?: { value: string; label: string }[];
};

type FieldBase = {
  key: string;
  label?: string;
  required: Requirement;
  appliesWhen?: Condition;
};

export type ScalarField = FieldBase & { kind: "scalar"; input: Input };

export type ObjectField = FieldBase & { kind: "object"; fields: Field[] };

export type CollectionField = FieldBase & {
  kind: "collection";
  cardinality?: Cardinality;
  constraints?: { uniqueItems?: boolean; sumEquals?: { field: string; value: number } };
  item: { kind: "scalar"; input: Input } | { kind: "object"; fields: Field[] };
};

export type ResourceField = FieldBase & {
  kind: "resource";
  resourceType: string;
  modes: ("existingResource" | "inlineData")[];
  dataFields?: Field[];
};

export type Field = ScalarField | ObjectField | CollectionField | ResourceField;

/** Current intake values, keyed by field key: the same object you PATCH under `requirements`. */
export type Values = Record<string, unknown>;

function conditionHolds(condition: Condition, values: Values): boolean {
  return values[condition.fieldKey] === condition.equals;
}

/** False means: hide the field, skip it in validation, ignore any stored value. */
export function evalAppliesWhen(field: Pick<Field, "appliesWhen">, values: Values): boolean {
  return field.appliesWhen === undefined || conditionHolds(field.appliesWhen, values);
}

/** Whether the field must be filled right now. A field that does not apply is never required. */
export function evalRequired(field: Pick<Field, "required" | "appliesWhen">, values: Values): boolean {
  if (!evalAppliesWhen(field, values)) return false;
  if (typeof field.required === "boolean") return field.required;
  return conditionHolds(field.required.when, values);
}

/**
 * Returns a copy of `items` padded with empty items up to `exact` (or `min`),
 * and trimmed down to `exact` (or `max`). Use it to decide how many inputs to render.
 */
export function padToCardinality<T>(
  items: readonly T[],
  cardinality: Cardinality | undefined,
  makeEmpty: () => T,
): T[] {
  const out = items.slice();
  if (!cardinality) return out;
  const floor = cardinality.exact ?? cardinality.min ?? 0;
  const ceiling = cardinality.exact ?? cardinality.max ?? Number.POSITIVE_INFINITY;
  while (out.length < floor) out.push(makeEmpty());
  if (out.length > ceiling) out.length = ceiling;
  return out;
}

function stableStringify(value: unknown): string {
  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
  if (value !== null && typeof value === "object") {
    const record = value as Record<string, unknown>;
    const entries = Object.keys(record)
      .sort()
      .map((k) => `${JSON.stringify(k)}:${stableStringify(record[k])}`);
    return `{${entries.join(",")}}`;
  }
  return String(JSON.stringify(value));
}

function uniquenessKey(item: unknown): string | null {
  if (item === null || item === undefined) return null;
  if (typeof item === "string") {
    const normalized = item.trim().toLowerCase();
    return normalized === "" ? null : `s:${normalized}`;
  }
  return `j:${stableStringify(item)}`;
}

/**
 * Index of the first item that repeats an earlier one, or -1.
 * Strings compare trimmed and case-insensitively; objects compare by JSON with sorted keys.
 * Blank items are skipped: they are missing, not duplicates.
 */
export function findUniqueItemsViolation(items: readonly unknown[]): number {
  const seen = new Set<string>();
  for (let i = 0; i < items.length; i++) {
    const key = uniquenessKey(items[i]);
    if (key === null) continue;
    if (seen.has(key)) return i;
    seen.add(key);
  }
  return -1;
}

type Block = { key: string; title: string; fields: Field[] };

type Row = {
  field: Field;
  required: boolean;
  items?: unknown[];     // collections: the padded list to render one input per item
  duplicateAt?: number;  // collections with uniqueItems: index to flag
};

export function planForm(blocks: Block[], values: Values): { key: string; title: string; rows: Row[] }[] {
  return blocks.map((block) => ({
    key: block.key,
    title: block.title,
    rows: block.fields
      .filter((field) => evalAppliesWhen(field, values))
      .map((field): Row => {
        const required = evalRequired(field, values);
        if (field.kind !== "collection") return { field, required };

        const item = field.item;
        const stored = Array.isArray(values[field.key]) ? (values[field.key] as unknown[]) : [];
        const items = padToCardinality<unknown>(stored, field.cardinality, () => (item.kind === "scalar" ? "" : {}));
        const dup = field.constraints?.uniqueItems ? findUniqueItemsViolation(items) : -1;
        return { field, required, items, duplicateAt: dup === -1 ? undefined : dup };
      }),
  }));
}

// With the Singapore schema and { registeredOfficeAddressSource: "getstartedService" },
// the registered office block has one row. Switch the value to "customerProvidedLocation"
// and a second, required row appears for registeredOfficeAddressLocation.