Coject.Workshop.Metadata 1.2.0

Coject.Workshop.Metadata

Coject.Workshop.Metadata is the ASP.NET-independent, generation-time library owned by Coject Workshop. It provides Workshop audit metadata, explicit custom-procedure contract validation, deterministic generation plans, and C# source-artifact helpers for controller and model audit workflows.

This is generation-time metadata/source-generation support. It is not runtime Controller integration: it does not register controllers, provide middleware or request handling, or execute audit logging at runtime. The package owns explicit custom-procedure metadata and generation; it does not infer business semantics from generated source or transport details.

Target framework

• net8.0

Installation and package boundary

<PackageReference Include="Coject.Workshop.Metadata" Version="1.2.0" />

The package depends exactly on the provider-neutral Coject.Core.Logging.Contracts version 3.1.0. It does not depend on Coject.Core.Logging or Coject.Core.Logging.AspNetCore, and it has no ASP.NET Core framework reference.

When an enabled generated Custom controller artifact is compiled into an ASP.NET Core application, that artifact has conditional generated-artifact dependencies on all three runtime packages:

<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
  <PackageReference Include="Coject.Core.Logging.Contracts" Version="3.1.0" />
  <PackageReference Include="Coject.Core.Logging" Version="1.3.0" />
  <PackageReference Include="Coject.Core.Logging.AspNetCore" Version="1.1.0" />
</ItemGroup>

These are dependencies of the generated artifact when it is included in the consuming application, not dependencies to add to the Workshop Metadata package. Contracts supplies the generated event/action, contract-shape, and authentication metadata; Core supplies the generated custom-procedure descriptor; and AspNetCore supplies the generated controller base class.

Minimal usage

The following uses the public metadata, planning, and generation APIs to render an inline model audit contract:

using Coject.Workshop.Metadata;

var metadata = new WorkshopModelAuditMetadata
{
    ModelType = "Acme.Models.Order",
    MutableAuditable = true,
    Fields =
    [
        new WorkshopModelFieldMetadata
        {
            PropertyName = "Id",
            ScalarKind = WorkshopAuditScalarKind.Int32,
            Identity = true
        },
        new WorkshopModelFieldMetadata
        {
            PropertyName = "Description",
            ScalarKind = WorkshopAuditScalarKind.String
        }
    ]
};

var plan = WorkshopModelAuditGenerationPlanner.CreatePlan(metadata);
var generatedSource = WorkshopModelAuditArtifactGenerator.RenderInlineModelSource(plan);

generatedSource is source text to apply to the model; the package does not add it to a project or deploy it for you.

Current scope and limitations

• Provides Workshop-owned metadata models, JSON metadata storage, validation, generation plans, and deterministic controller/model audit source artifacts.
• The current model planner supports the scalar kinds defined by WorkshopAuditScalarKind; mutable auditable models require exactly one supported identity field. Read/report models can opt out with MutableAuditable = false.
• The v2 metadata schema adds explicit custom-procedure contract shape, input/data-return declarations, authentication mode, and event/action policy. Legacy v1 operation-controller documents remain readable; legacy custom actions without these declarations are rejected rather than semantically inferred.
• Custom controller output selects one of the three explicit ASP.NET custom-procedure controller base classes from the declared contract shape.
• Generated output is intended to be consumed by the calling build or generation workflow. Operation artifacts can remain provider-neutral; a generated custom-controller artifact conditionally requires the runtime package set described above.
• Runtime Controller integration, Baha API runtime integration, hosting, and production deployment are outside this package's scope.

Explicit custom-procedure semantics

For a Custom controller, metadata must explicitly declare the transport contract and business meaning. In addition to the required module, resource, operation, and target metadata, custom actions declare:

• contractShape with matching input and/or dataReturn declarations;
• intent, event, and action for business classification;
• authenticationMode and, when applicable, an explicit bounded userId;
• Single or Batch execution shape, success rule, audit mode, and identity provenance.

Business event/action is never inferred from the procedure name, controller name, route, HTTP verb, CLR request type, CLR response type, or result count. For example, DeleteReport, a DELETE route, or a single-item result does not by itself select DataDeletion/Delete. Declare the pair explicitly, such as DataRead/Read, DataCreation/Create, or DataModification/Execute; Workshop validates compatibility with the declared intent and execution shape. Single/Batch is item cardinality and is separate from the transport contract shape.

An illustrative explicit fragment is:

{
  "actionName": "RunReport",
  "event": "DataCreation",
  "action": "Create",
  "intent": "Create",
  "contractShape": "ReturnsDataWithInput",
  "input": { "type": "Acme.Models.ReportRequest" },
  "dataReturn": { "type": "Acme.Models.Report" },
  "authenticationMode": "AuthenticatedUser"
}

The complete controller action also supplies the required audit, success, target, and identity metadata.

Generated controller base classes

The generated custom-controller class inherits from one base selected by the declared contractShape:

These three base classes classify transport contract shape only. They do not classify read/create/modify/delete/workflow intent, choose the event/action pair, choose authentication, or determine Single versus Batch cardinality. All actions in one generated custom controller use one consistent declared contract shape, and the explicit input/data declarations must agree with it.

Authentication modes

authenticationMode is explicit:

• Anonymous means no authorizer and no user ID are required. Omit userId; Workshop preserves it as null and does not synthesize an identity from the request, route, or name. The ASP.NET Core adapter skips its authorizer hook for an anonymous descriptor.
• AuthenticatedUser is the authenticated-caller mode. The host can provide ICustomProcedureAuthorizer<TRequest> to enforce its authentication and authorization policy. An explicit bounded userId may be carried as metadata, but generation never infers or fabricates it.

Current aligned releases

Use this version set when Workshop metadata and a generated custom-controller artifact are consumed together:

Coject.Workshop.Metadata.Mapping is optional and is not a runtime dependency of the generated controller base classes.