SchemaSchema: A method for declaring and managing your project’s data model

SchemaSchema is a language I wrote for declaring a data model and a Java library that interprets it. Here’s some example schema:

resource class 'provider type' : scope @ constant {
        provider type code : string : key(primary)
        name : string
        is community resource type : boolean
    }
    
    resource class 'provider' : scope @ org-tree {
        ID : entity ID : key(primary)
        defining organization ID : entity ID
        provider type code : string
        name : string : nullable
        name prefix : string : nullable
        first name : string : nullable
        last name : string : nullable
        name suffix : string : nullable
        description : string
        e-mail address : string : nullable
        phone number : string : nullable
        website URL : string : nullable
        address : postal address : nullable
    }

You may ask: Why not just write your CREATE TABLE scripts in SQL and call that your data model?

SchemaSchema allows you to define common data types and use them over and over. If the definitions change (e.g. a user ID used to be represented as a 32-bit integer but now it needs to be 64 bits) you can simply change the definition and re-generate your table creation SQL. If you need to upgrade your database, you can use SchemaSchema to find all columns of type ‘user ID’ and write the appropriate ALTER TABLE statements.

SchemaSchemas can also declare things about your schema that aren’t limited to how it’s represented in the database. E.g. you can indicate how certain values should be encoded in JSON or PHP. In First30 we have various object ‘scopes’ that influence who is allowed to view and edit them, and the SchemaSchema document indicates the scope for each table, allowing us to auto-generate data used by the permission checking functions and service tests.

The result of all this auto-generation is that when we need to change something about our schema, we can change it once in schema.txt and let the computer do all the work that for a human to do would be incredibly tedious and error-prone (updating the database and all references to the changed tables).

The schema document also serves as a central piece of documentation that’s more easily readable than your table creation SQL.