Discover and validate expressions

Resolve all /api/workspace/... routes against the configured installation’s WORKSPACE_API_BASE_URL, never against moltaro.com. Obtain exact DTOs and numeric enum values from that installation’s Configuration OpenAPI. The public reference may describe a newer release.

Every expression belongs to an editing subject: an Entity Definition, field, Board, Workflow Definition or Task Outcome. Its authoring description is the source of truth for available paths and operations. Reading that description requires the subject’s configuration permissions and grants no record access.

Entity validation and discovery

Add "IncludeAuthoring": true to a validation request to receive Authoring from the same schema used to check the expression:

Setting	POST route under /api/workspace/admin	Source property	Result flag
Field behavior, mutation effects, presentation and Entity Statements	entity-definitions/{id}/rule-expressions/validate	Value, with ContextType and ExpressionType	IsValid
Validation rule	entity-definitions/{id}/validation-rules/validate-expression	Expression	Valid
Calculated field	entity-fields/{id}/calculation/validate	Expression	Valid
Reference Eligibility	entity-fields/{id}/reference-eligibility/validate	Expression	Valid

POST /api/workspace/admin/entity-fields/{fieldId}/calculation/validate
Content-Type: application/json

{"Expression":"ROUND(Qty * Price, 2)","IncludeAuthoring":true}

This example needs compatible numeric fields and a numeric calculation target. Inspect the corresponding Data.Valid or Data.IsValid flag and Data.Errors, not just the HTTP status or outer Success. A parsed request can return successful validation transport with an invalid expression. Authoring metadata can accompany invalid source; it may be absent when the subject has no supported schema.

The shared rule-expression request additionally accepts ExpectedDescriptorFingerprint when IncludeAuthoring is true. On a match, BaseDescriptorFingerprint identifies the description and the server omits the unchanged Authoring body. A mismatch reports moltaro.dsl.authoring.schemaChanged; reload metadata and revalidate. The other three requests do not have this fingerprint field.

For field behavior, pass EntityDefinitionTableId. The request can also describe an unsaved root field through its PendingRoot... properties; these are validation context, not a schema write.

Reading an authoring description

• SourceKind distinguishes Condition, Value and Template. ExpectedFamily describes the expected result where applicable.
• Roots supplies paths and collections. Use each path’s admitted operators; a general profile operator does not apply to every family.
• OperatorForms gives actual syntax, including ANY/ALL only where collections are admitted. Operations gives functions, signatures, overloads, argument constraints and SQL/preview availability.
• SyntaxForms describes host forms such as HAS_ROLE, RESPONSIBLE and Board target selectors, including currently valid choices.
• PredicateAdmission, ComparisonAdmission, OperandAdmission and ValueAdmission add owner restrictions. For example, calculated-field aggregates must be the whole expression and ROUND permits at most six places on that surface.
• Template describes placeholder syntax, functions, eager argument evaluation and per-placeholder limits.
• Examples are checked against the described subject. They are more useful than copying a field name from an unrelated definition.

Keep DescriptorFingerprint as an opaque identity for this editing context. Do not synthesize it from the other fingerprints. Metadata assists authoring; saving still recompiles the exact source against the current schema.

Security descriptions and paged paths

Entity Security uses:

GET  /api/workspace/admin/entity-definitions/{id}/security/authoring-options
POST /api/workspace/admin/entity-definitions/{id}/security/authoring-paths
POST /api/workspace/admin/entity-definitions/{id}/security/authoring-validate

Board Security reads /api/workspace/admin/boards/boards/{boardId}/security/authoring-options; its path and validation routes are under security/profiles/{resourceKind}/authoring-paths and security/profiles/{resourceKind}/authoring-validate. Select the returned Profiles entry by ResourceKind and check its Errors before using Authoring.

The initial description does not eagerly list every relationship path. Request direct members of a prefix without a trailing dot:

{
  "ExpectedDescriptorFingerprint": "<description identity>",
  "Prefix": "item",
  "CollectionScope": null,
  "Offset": 0,
  "Limit": 50
}

Use returned NextOffset for continuation and send page zero’s ResolvedDescriptorFingerprint as ExpectedResolvedDescriptorFingerprint on subsequent pages. Stop when NextOffset is null. A changed base or resolved identity requires fresh discovery, not mixing pages.

Inside a predicate, use CollectionScope and an item-relative Prefix. For ANY item.Assemblies WHERE (ALL Components WHERE (...)), discover the inner item’s members with CollectionScope: "Components", OuterCollectionScopes: ["item.Assemblies"] and Prefix: "". Follow CanExpand; do not guess descendants.

Validate source with:

{
  "ExpectedDescriptorFingerprint": "<description identity>",
  "Source": "COUNT(item.Assemblies) > 0 AND ALL item.Assemblies WHERE (State = 'built')"
}

Inspect Data.Valid and Data.Diagnostics; this validation family differs from the Entity validation shapes above. Schema and authorization failures use the outer API error envelope.

Board, Workflow and Task owners

Board Statements have their own authoring, validation and preview endpoints in the Configuration API. Target scope is part of their description.

Workflow exposes separate descriptions for User Input permission DSL, activation permission DSL, activation business preconditions and DevLog templates. Use that setting’s own description, path-page and validation operations; permission and business-condition descriptors are not interchangeable. Workflow configuration HTTP operations are in the installed Configuration OpenAPI. The Workflow guide also describes the supported C# services.

Task completion is Outcome-specific. Discover and validate it through the Tasks configuration HTTP operations in the installed Configuration OpenAPI or the supported Tasks C# configuration services.

Diagnostics and the save boundary

Positioned diagnostics count zero-based UTF-16 code units in the submitted source; End is exclusive. Some owner responses use a start and length; read the installed response schema and SourcePositions instead of treating offsets as UTF-8 bytes or line numbers.

After correcting errors, save exactly the validated source with the current owner concurrency token. A valid description or preview is not a reservation: schema, permissions and dependencies can change before the save. Read back the saved setting and verify the intended behavior through its owning feature.