Aeria Schema

Schemas in Aeria are defined using a superset of JSON Schema with framework-specific attributes. Schemas used to define the data structure of collections are referred to as descriptions.

• JSON Schema
  • $id
  • required
  • properties Record<string, Property>
• Description
  • actions CollectionActions<TDescription>? frontend
  • filters frontend
  • filtersPresets Record<string, FiltersPreset<TDescription>>? frontend
  • form frontend
  • formLayout Partial<FormLayout<TDescription>>? frontend
  • icon string? frontend
  • immutable (boolean | readonly string[])?
  • indexes readonly string? frontend
  • individualActions CollectionIndividualActions<TDescription>? frontend
  • owned (boolean | 'always')?
  • table readonly PropertiesWithId<TDescription>? frontend
  • tableMeta readonly PropertiesWithId<TDescription>[]? frontend
  • timestamps false?
  • layout Layout?
  • preset readonly CollectionPresets[]?
  • writable readonly PropertiesWithId<TDescription>[]?
  • search SearchOptions?

JSON Schema

$id

As in JSON Schema, this property is used to name the structure we are defining. It must have the same name as the collection. Collection names must consist of a camel-cased noun in the singular, like person, fruit or car. In Aeria Lang this property is implicit.

required

main.aeria

collection Example {
  required {
    name
    document
    // legal responsible is only required if age is lesser than 18 on insertion
    legal_responsible @cond(age < 18)
  }
}

collection.ts

defineCollection({
  description: {
    required: {
      name: true
      document: true,
      document: {
        if: {
          operator: 'lt',
          term1: 'age',
          term2: 18,
        },
      },
    },
  },
})

types.ts

type RequiredProperties<TDescription extends Description> = readonly PropertiesWithId<TDescription>[] | Partial<Record<
  PropertiesWithId<TDescription>,
  Condition<TDescription> | boolean
>>

This property is used to verify document wholeness upon creation and update. Case set to an array of strings, will consider only specified properties to validate document wholeness, otherwise will check if all properties are not null or undefined.

properties Record<string, Property>

The properties contained in the collection. Properties are described in a separate section.

Description

actions CollectionActions<TDescription>? frontend

Actions that aren't associated with a single database entry.

main.aeria

collection Example {
  actions {
    add {
      label "Add new entry"
    }
  }
}

collection.ts

defineCollection({
  description: {
    actions: {
      add: {
        label: 'Add new entry',
      },
    },
  },
})

types.ts

type CollectionActionRoute = {
  route: {
    name: string
    setItem?: boolean
    fetchItem?: boolean
    clearItem?: boolean
    params?: Record<string, unknown>
    query?: Record<string, unknown>
  }
}

type CollectionActionFunction = {
  function?: string
  selection?: boolean
  effect?: string
}

type CollectionActionEvent = {
  event?: string
}

type CollectionActionBase<TDescription extends Description> = {
  label?: string
  icon?: Icon
  ask?: boolean
  translate?: boolean
  roles?: readonly string[]
  requires?: readonly PropertiesWithId<TDescription>[]
}

export type CollectionAction<TDescription extends Description> = CollectionActionBase<TDescription> & (
  | CollectionActionRoute
  | CollectionActionFunction
  | CollectionActionEvent
)

export type CollectionActions<TDescription extends Description> = Record<
  string,
  | CollectionAction<TDescription> & {
    button?: boolean
  }
  | null
>

filters frontend

This property is used to control a filter widget rendered inside the aeria-crud component. If set, a filter button will appear, otherwise no filter functionallity will be made available.

The array passed to this property can contain two types of elements, either a string representing a property name, or an object containing both the property name and a default filter.

main.aeria

collection Example {
  filters {
    name
  }
}

collection.ts

defineCollection({
  description: {
    filters: [
      'name',
    ],
  },
})

type.ts

type DescriptionFilters = readonly (PropertiesWithId<TDescription> | {
  property: PropertiesWithId<TDescription>
  default: string
})[]

filtersPresets Record<string, FiltersPreset<TDescription>>? frontend

main.aeria

collection Example {
  filtersPresets {
    active {
      label "Active"
      filters {
        active true
      }
    }
  }
}

collection.ts

defineCollection({
  description: {
    filtersPresets: {
      active: {
        label: 'Active',
        filters: {
          active: true,
        },
      },
    },
  },
})

type.ts

type FiltersPreset<TDescription extends Description> = {
  label?: string
  icon?: string
  filters: Partial<Record<PropertiesWithId<TDescription> | `$${string}`, any>>
  table?: Array<PropertiesWithId<TDescription>>
  badgeFunction?: string
  default?: boolean
}

type FiltersPresets<TDescription extends Description> = Record<string, FiltersPreset<TDescription>

form frontend

If set, runtime generated forms will render only specified properties. Otherwise all properties are rendered.

WARNING

This property alone won't keep any of non-specified collection properties to be written. If you need to make properties read-only, use the writable property in an exclusive manner.

main.aeria

collection Example {
  form {
    name
    document
  }
}

collection.ts

defineCollection({
  description: {
    form: [
      'name',
      'document',
    ],
  },
})

types.ts

type Form = readonly PropertiesWithId<TDescription>[] | Record<PropertiesWithId<TDescription>, string[]>

formLayout Partial<FormLayout<TDescription>>? frontend

This property controls how inputs should be dynamically rendered inside frontend forms.

main.aeria

collection Example {
  formLayout {
    fields {
      responsible @if(age == 18)
    }
  }
}

collection.ts

defineCollection({
  description: {
    formLayout: {
      fields: {
        responsible: {
          if: {
            operator: 'lt',
            term1: 'age',
            term2: 18,
          }
        }
      }
    },
  },
})

types.ts

type FormLayout<TDescription extends Description> = {
  fields?: Partial<Record<PropertiesWithId<TDescription>, FormLayoutField<TDescription>>>
}

type FormLayoutField<TDescription extends Description> = {
  span?: number
  verticalSpacing?: number
  separator?:
    | true
    | 'top'
    | 'bottom'
  if?: Condition<TDescription>
  component?: {
    name: string
    props?: Record<string, any>
  }
}

icon string? frontend

This property may be used to specify an icon from an icon library to be associated with the collection in the frontend. It will be shown on navbars, breadcumbs, etc.

main.aeria

collection Example {
  icon "file"
}

collection.ts

defineCollection({
  description: {
    icon: 'file',
  },
})

types.ts

type SearchOptions<TDescription extends Description> = {
  placeholder?: string
  indexes: readonly (keyof TDescription['properties'])[]
}

immutable (boolean | readonly string[])?

This property may be used to specify properties that should be writable upon creation, but read-only upon update. If set to true, then will enable immutability to all properties, if set to an array of strings, only specified properties will receive that attribute.

main.aeria

collection Example {
  immutable {
    status
  }
}

collection.ts

defineCollection({
  description: {
    immutable: [
      'status',
    ],
  },
})

types.ts

type DescriptionImmutable<TDescription extends Description> =
  | boolean
  | readonly (keyof TDescription['properties'])[]
  | ((doc: WithId<any>)=> boolean | Promise<boolean>)

indexes readonly string? frontend

This optional property may be used to specify an icon from an icon library to be associated with the collection in the frontend. It will be shown on navbars, breadcumbs, etc.

main.aeria

collection Example {
  indexes {
    name
    document
  }
}

collection.ts

defineCollection({
  description: {
    indexes: [
      'name',
      'document',
    ],
  },
})

types.ts

type DescriptionIndexes = readonly PropertiesWithId<TDescription>[]

individualActions CollectionIndividualActions<TDescription>? frontend

Actions associated with a single database entry. In a tabular layout, these are displayed inside a dropdown in the last column.

main.aeria

collection Example {
  individualActions {
    remove {
      label "Remove"
    }
  }
}

collection.ts

defineCollection({
  description: {
    individualActions: {
      remove: {
        label: 'Remove',
      },
    },
  },
})

types.ts

type CollectionIndividualActions<TDescription extends Description> =
  Record<string, CollectionAction<TDescription> | null>

owned (boolean | 'always')?

This property is used to control the access of user-owned resources. If set to true or 'always' in a description, users will only be able to view and edit resources created by themselves.

main.aeria

collection Example {
  owned true
}

collection.ts

defineCollection({
  description: {
    owned: true,
  },
})

types.ts

type OwnershipMode =
  | boolean
  | 'always'
  | 'on-write'

type DescriptionOwned = OwnershipMode

table readonly PropertiesWithId<TDescription>? frontend

This property is used exclusively by the frontend. Case set to an array of strings, will specify properties to be used as columns in aeria-crud component. Otherwise all properties will be used.

NOTE

In the frontend, Aeria will smartly request only required properties in order to make network payloads lighter. This is specialy important in runtime generated views. If you need to use a property that isn't set as a column inside your view, please add the tableMeta property.

main.aeria

collection Example {
  table {
    name
    document
  }
}

collection.ts

defineCollection({
  description: {
    table: [
      'name',
      'document',
    ],
  },
})

types.ts

type DescriptionTable = readonly PropertiesWithId<TDescription>[]

tableMeta readonly PropertiesWithId<TDescription>[]? frontend

If set, grid and tabular runtime generated views will request the specified properties alongside the ones specified in table.

main.aeria

collection Example {
  tableMeta {
    extra_property
  }
}

collection.ts

defineCollection({
  description: {
    tableMeta: [
      'extra_property',
    ],
  },
})

types.ts

type DescriptionTableMeta = readonly PropertiesWithId<TDescription>[]

timestamps false?

This property should only be used to disable automatic timestamps in a certain collection (created_at and updated_at). Timestamps are always enabled by default.

main.aeria

collection Example {
  timestamps false
}

collection.ts

defineCollection({
  description: {
    timestamps: false,
  },
})

types.ts

type DescriptionTimestamps = false

layout Layout?

Specifies a layout to override the default tabular one.

main.aeria

collection Example {
  layout {
    name "tabular"
    options {
      title title
    }
  }
}

collection.ts

defineCollection({
  description: {
    layout: {
      name: 'tabular',
      options: {
        title: 'title,'
      },
    },
  },
})

types.ts

type LayoutName =
  | 'tabular'
  | 'grid'
  | 'list'

type LayoutOptions<TDescription extends Description = any> = {
  picture?: PropertiesWithId<TDescription>
  title?: PropertiesWithId<TDescription>
  badge?: PropertiesWithId<TDescription>
  information?: PropertiesWithId<TDescription>
  active?: PropertiesWithId<TDescription>
  translateBadge?: boolean
}

type Layout<TDescription extends Description = any> = {
  name: LayoutName
  options?: LayoutOptions<TDescription>
}

preset readonly CollectionPresets[]?

Merges a description preset into the current one. To see what each preset contains please head to the source code.

main.aeria

collection Example {
  presets {
    crud
    view
  }
}

types.ts

type DescriptionPreset =
  | 'crud'
  | 'duplicate'
  | 'remove'
  | 'removeAll'
  | 'owned'
  | 'timestamped'
  | 'view'

writable readonly PropertiesWithId<TDescription>[]?

If set, all properties except the one specified will be made read-only. Trying writing on them will trigger an Access Control error.

main.aeria

collection Example {
  writable {
    name
    document
  }
}

collection.ts

defineCollection({
  description: {
    writable: [
      'name',
      'document',
    ],
  },
})

types.ts

type DescriptionWritable = readonly PropertiesWithId<TDescription>[]

search SearchOptions?

Activates a search bar in the frontend that will perform a MongoDB $text query.

main.aeria

collection Example {
  search {
    placeholder "Something"
    indexes {
      name
      document
    }
  }
}

collection.ts

defineCollection({
  description: {
    search: {
      placeholder: 'Something',
      indexes: [
        'name',
        'document',
      ],
    },
  },
})

types.ts

type DescriptionSearch<TDescription extends Description> = {
  placeholder?: string
  indexes: readonly (keyof TDescription['properties'])[]
}