@spec add_field_at_path(Zoi.schema(), [atom()], atom(), Zoi.schema()) :: Zoi.schema()

Add a field at a path within a schema.

Uses Zoi.Schema.traverse/2 to locate the insertion point. Traverse automatically descends through Default wrappers and dynamic-key map value_types, so no special :* markers are needed.

Path is a list of atom keys matching the traverse path. An empty path adds the field at the root level (handled directly since traverse does not visit the root node).

Examples:

# Add :aws at the top level
add_field_at_path(schema, [], :aws, @aws_schema |> Zoi.optional())

# Add :s3 inside the :aws field
add_field_at_path(schema, [:aws], :s3, @s3_schema |> Zoi.optional())

# Add a field to every deploy's release (traverse descends into dynamic maps)
add_field_at_path(schema, [:deploys, :releases], :custom, Zoi.string())

@spec add_refinement_at_path(Zoi.schema(), [atom()], {module(), atom(), keyword()}) ::
  Zoi.schema()

Attach a Zoi.refine/2 refinement at a path within a schema.

Mirrors add_field_at_path/4 but wraps the matched node in a refinement (a {Module, fun, opts} MFA tuple) instead of adding a field. Useful for cross-field validations contributed by plugins.

Path is a list of atom keys matching the traverse path. An empty path refines the root schema.

Examples:

# Refine each deploy entry (traverse descends into the dynamic map)
add_refinement_at_path(schema, [:deploys], {MyMod, :validate_deploy, []})

@spec base_schema([atom()], [atom()]) :: Zoi.schema()

Returns the base Zoi schema for marea.yaml, with the deploy and release type: enums populated from deploy_types / release_types.

deploy_types is the list collected by the Marea.Plugins.Base.marea_deploy_types/1 chain; release_types is the list from Marea.Plugins.Base.marea_release_types/1. For each list:

• one or more values — the corresponding type: field is optional and defaults to the first entry in the list (so a release with no explicit type: resolves to the first plugin's contribution; chain order matters);
• empty — type: is omitted entirely. Any explicit type: in the YAML will be flagged as an unknown key.

@spec compose() :: Zoi.schema()

Returns the full plugin-enriched schema.

Runs the Marea.Plugins.Base.marea_deploy_types/1, Marea.Plugins.Base.marea_release_types/1 and Marea.Plugins.Base.marea_config_schema/1 chains over the currently loaded plugins and returns the resulting schema. Used by marea schema show and any caller that needs to introspect the live, fully extended schema.

@spec get_yaml_config(keyword()) :: {String.t(), map()}

Pulls {yaml_path, yaml_terms} out of the service config keyword.

@spec to_json(Zoi.schema()) :: String.t()

Renders schema as a pretty-printed JSON Schema string.

@spec to_tree(Zoi.schema()) :: String.t()

Renders schema as a human-readable indented tree (used by marea schema show). Each field is shown with its type label, required/default annotation, and description.

@spec validate(map()) :: {:ok, map()} | {:error, String.t()}

Validates a YAML map against the base schema (no plugin enrichment).

@spec validate!(String.t(), map(), Zoi.schema()) :: map() | no_return()

Validates terms against schema using Zoi.parse/2.

Returns the validated map on success; aborts with a formatted error message that points at path on failure.