module Athena::DependencyInjection::Extension::Schema

Overview

Used to denote a module as an extension schema. Defines the configuration properties exposed to compile passes added via ADI.add_compiler_pass. Schemas must be registered via ADI.register_extension.

EXPERIMENTAL This feature is intended for internal/advanced use and, for now, comes with limited public documentation.

Member Markup

#object_of and #array_of support a special doc comment markup that can be used to better document each member of the objects. The markup consists of --- to denote the start and end of the block. >> denotes the start of the docs for a specific property. The name of the property followed by a : should directly follow. From there, any text will be attributed to that property, until the next >> or ---. Not all properties need to be included.

For example:

module Schema
  include ADI::Extension::Schema

  # Represents a connection to the database.
  #
  # ---
  # >>username: The username, should be set to `admin` for elevated privileges.
  # >>port: Defaults to the default PG port.
  # ---
  object_of? connection, username : String, password : String, port : Int32 = 5432
end

WARNING The custom markup is only supported when using mkdocs with some custom templates.

Defined in:

extension.cr

Macro Summary

Macro Detail

macro array_of(name, *members) #

Similar to #object_of, but defines an array of objects.

module Schema
  include ADI::Extension::Schema

  array_of rules,
    path : String,
    value : String
end

ADI.register_extension "test", Schema

ADI.configure({
  test: {
    rules: [
      {path: "/foo", value: "foo"},
      {path: "/bar", value: "bar"},
    ],
  },
})

If not provided, the property defaults to an empty array.


[View source]
macro array_of?(name, *members) #

Same as #array_of but makes the default value of the property nil.


[View source]
macro map_of(name, *members) #

Defines a map where keys are arbitrary names and values follow a typed object schema. This is useful for configuration patterns where named entries share a common structure.

module Schema
  include ADI::Extension::Schema

  map_of hubs,
    url : String,
    port : Int32 = 5432
end

ADI.register_extension "test", Schema

ADI.configure({
  test: {
    hubs: {
      primary:   {url: "localhost"},
      secondary: {url: "remote", port: 5433},
    },
  },
})

If not provided, the property defaults to an empty map.


[View source]
macro map_of?(name, *members) #

Same as #map_of but makes the default value of the property nil.


[View source]
macro object_of(name, *members) #

Defines a required strictly typed NamedTupleLiteral object with the provided name and members. The members consist of a variadic list of declarations, with optional default values.

module Schema
  include ADI::Extension::Schema

  object_of connection,
    username : String,
    password : String,
    hostname : String = "localhost",
    port : Int32 = 5432
end

ADI.register_extension "test", Schema

ADI.configure({
  test: {
    connection: {username: "admin", password: "abc123"},
  },
})

This macro is preferred over a direct NamedTuple type as it allows default values to be defined, and for the members to be documented via the special [Member Markup][Athena::DependencyInjection::Extension::Schema--member-markup]


[View source]
macro object_of?(name, *members) #

Same as #object_of but makes the object optional, defaulting to nil.


[View source]
macro object_schema(name, *members) #

Defines a reusable object schema that can be referenced by name in other schema definitions. This is useful for defining nested object structures or sharing schemas between properties.

module Schema
  include ADI::Extension::Schema

  object_schema JwtConfig,
    secret : String,
    algorithm : String = "hmac.sha256"

  map_of hubs,
    url : String,
    jwt : JwtConfig
end

NOTE Object schemas must be defined before they are referenced.


[View source]
macro property(declaration) #

Defines a schema property via the provided declaration. The type may be any primitive Crystal type (String, Bool, Array, Hash, Enum, Number, etc).

module Schema
  include ADI::Extension::Schema

  property enabled : Bool = true
  property name : String
end

ADI.register_extension "test", Schema

ADI.configure({
  test: {
    name: "Fred",
  },
})

[View source]