Schema und Code

Die Schema-Datei

Neben einer Vorlage kann ein JSON Schema mit demselben Namen liegen:

rechnung.md
rechnung.schema.json

Gibt es die Datei, prüfen brevier pdf und brevier html zwei Dinge, bevor sie drucken:

1. Jeder {{ }}-Tag in der Vorlage nennt ein Feld, das das Schema kennt.
2. Die Daten passen zum Schema: Pflichtfelder, Typen, Listen.

Schlägt eine Prüfung fehl, wird nichts gedruckt. Brevier listet jedes Problem auf, bei der ersten Prüfung mit der Zeile in der Vorlage.

Ohne Schema-Datei überspringt Brevier beide Prüfungen.

--schema wählt ein anderes Schema: den Pfad einer Datei, oder false, um die Prüfungen auszulassen.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "rechnung": {
      "type": "object",
      "properties": {
        "nummer": { "type": "string", "title": "Rechnungsnummer" },
        "summe": { "type": "number", "format": "decimal" }
      },
      "required": ["nummer", "summe"]
    }
  },
  "required": ["rechnung"]
}

Aus Ihren Klassen

Sie müssen das Schema nicht von Hand schreiben. Es entsteht in zwei Schritten aus den Klassen, die Sie heute schon an Ihre alte PDF-Bibliothek übergeben. Ihre Klassen brauchen kein Brevier-Interface, keine Basisklasse und keine Annotation.

1. Das Schema schreiben

In Java liest ein Build-Schritt Ihre kompilierten Klassen. brevier-codegen.jar entsteht beim Build des Java-Clients.

java -cp build/classes:brevier-codegen.jar dev.brevier.codegen.SchemaGeneratorCommand \
  --root rechnung=com.ww.Rechnung --root kunde=com.ww.Kunde > rechnung.schema.json

Jedes --root ist ein Feld auf der obersten Ebene der Daten: name=klasse. Für eine Liste hängen Sie [] an die Klasse: --root positionen=com.ww.Position[].

In Python liest brevier.schema() Dataclasses, Pydantic-v2-Modelle, attrs-Klassen, TypedDicts, Django-Modelle und SQLAlchemy-Modelle:

import json
from pathlib import Path

import brevier
from billing.models import Kunde, Rechnung

schema = brevier.schema(Rechnung, kunde=Kunde)
Path("rechnung.schema.json").write_text(json.dumps(schema, indent=2), encoding="utf-8")

Eine Klasse ohne Namen bekommt den Klassennamen mit kleinem Anfangsbuchstaben: aus Rechnung wird rechnung.

In C# liest BrevierSchema.Create() Ihre Klassen:

using System.IO;
using System.Text.Json;
using Brevier;

var schema = BrevierSchema.Create(typeof(Rechnung), typeof(Kunde));
File.WriteAllText("rechnung.schema.json", schema.ToJsonString(new() { WriteIndented = true }));

2. Die Vorlage schreiben

brevier template --schema rechnung.schema.json

Das legt drei Dateien neben das Schema:

--format md schreibt eine Markdown-Vorlage statt HTML. brevier template überschreibt nie eine Datei. Gibt es eine der drei Dateien schon, schreibt es keine. Mit --force werden alle ersetzt.

Aus einem Datensatz

Wenn Sie einen echten Datensatz haben, aber keine Klassen, schreibt scaffold alle vier Dateien daraus: das Schema, die Vorlage, das Stylesheet und die Beispieldaten.

brevier scaffold --from rechnung.json

Aus einer Vorlage

Wenn Sie die Vorlage haben, schreibt from-template das Schema, das sie braucht. Mit --lang java17 schreibt es auch Java-Klassen für die Daten.

brevier from-template rechnung.html

Alle Optionen stehen unter Kommandozeile.

Der TypeScript-Client liest Typen noch nicht. Nutzen Sie brevier scaffold --from rechnung.json oder schreiben Sie das Schema von Hand.