Interfaces

1 Define an Interface

Declare shared fields in the interfaces section. Interfaces are abstract — they cannot be instantiated directly.

"interfaces": {
  "person": {
    "fields": [
      { "name": "email", "type": "string", "required": false },
      { "name": "name", "type": "string", "required": false }
    ]
  }
}

A Scala generator produces:

sealed trait Person {
  def email: Option[String]
  def name: Option[String]
}

2 Extend from a Model

List interface names in a model's interfaces array. The model must include all interface fields with matching name, type, and required status.

"models": {
  "guest": {
    "interfaces": ["person"],
    "fields": [
      { "name": "session_id", "type": "string" },
      { "name": "email", "type": "string", "required": false },
      { "name": "name", "type": "string", "required": false }
    ]
  }
}

Generated Scala:

case class Guest(
  sessionId: String,
  override val email: Option[String] = None,
  override val name: Option[String] = None
) extends Person

3 Use with Union Types

Union types can also implement interfaces. When a union declares an interface, every type in the union automatically inherits it — no need to repeat the interface on each member.

"unions": {
  "person": {
    "discriminator": "discriminator",
    "interfaces": ["person"],
    "types": [
      { "type": "guest" }
    ]
  }
}

The guest model automatically inherits the person interface through the union — no explicit declaration needed on the model.

! Key Rules

• Validation — Fields must match by name, type, and required status
• Multiple interfaces — Models can extend zero or more interfaces
• Union shortcut — A union and interface can share the same name if the union explicitly lists the interface

Resources

• Complete interface example — Full api.json demonstrating all interface features
• api.json specification — Full format reference