Velden

Zodra je collecties hebt aangemaakt, ga je bepalen welke informatie elk item binnen zo’n collectie moet bevatten. Dat doe je met velden. Een veld beschrijft een enkel stukje data binnen een item: van de naam van een product tot de publicatiedatum van een blogpost of de voorraadstatus in een magazijn. Velden vormen daarmee het skelet van je gegevensstructuur — ze bepalen wat er wél en niet mag worden opgeslagen.

Wat is een veld?

Een veld is een eigenschap van een item binnen een collectie. Elk veld heeft een naam en een datatype: zo kun je bijvoorbeeld aangeven dat het veld description tekst bevat, dat price een getal is, of published een datum. Daarnaast kun je met aanvullende properties zoals required, min, max en default precies aangeven hoe de data wel of niet geaccepteerd wordt.

Stel: je bouwt een webshop en je wilt producten opslaan. Dan wil je bijvoorbeeld een veld name, price en imageUrl. Een price-veld mag geen negatieve getallen bevatten, dus stel je de minimumwaarde in op 0. Voor een blogpost zou je misschien velden willen zoals title,content, author en publishedAt, waarbij de publicatie-datum altijd de datum is waarop deze blogpost aan de database is toegevoegd.

Veldstructuur

In de NOVI Dynamic API definieer je velden via het fields-gedeelte in je JSON-configuratie. Elk veld bevat minimaal de volgende onderdelen:

• name: de naam van het veld (bijvoorbeeld "price")
• type: het datatype (zoals "string" of "number")
• required: geeft aan of het veld verplicht is if niet ("true" of "false")

Daarnaast kun je extra validatieregels toevoegen:

• min: de minimale lengte (bij tekst) of minimale waarde (bij getallen)
• max: de maximale lengte (bij tekst) of maximale waarde (bij getallen)
• default: de standaardwaarde die ingevuld wordt als er niks wordt opgegeven

{
  "collections": [
    {
      "name": "products",
      "fields": [
        {
          "name": "id",
          "type": "number",
          "required": true
        },
        {
          "name": "name",
          "type": "string",
          "required": true,
          "min": 2,
          "max": 100
        },
        {
          "name": "price",
          "type": "number",
          "required": false,
          "min": 0,
          "default": 0
        }
      ],
      "permissions": {
        // Zie hoofdstuk 'Rollen en Permissies'
      }
    }
  ]
}

Let op: elke collectie moet minimaal een verplicht id-veld bevatten. Dit is de unieke sleutel waarmee elk item wordt geïdentificeerd.

Ondersteunde datatypes

De API ondersteunt de volgende datatypes:

*Voor meer informatie over het gebruik van afbeeldingen, zie Afbeeldingen.

Validatieregels

Je kunt verschillende validatieregels instellen om de invoer te beperken:

Let op: Gebruik een default-waarde alleen bij velden die niet verplicht zijn. Als een veld wél verplicht is ( required: true), dan móét de gebruiker daar zelf iets invullen voordat het item opgeslagen kan worden. Een standaardwaarde heeft dan geen effect, want die wordt toch nooit gebruikt.

Tip: wil je datum-veld automatisch laten invullen met de datum van vandaag? Dat kan op de volgende manier:

{
  "name": "createdAt",
  "type": "date",
  "required": false,
  "default": "CurrentDate"
}

Dit veld hoeft dan niet telkens ingevuld te worden door de gebruiker, het systeem vult dit veld zelf in bij het aanmaken van een nieuw item.

Relaties via referentievelden

Met het reference-type kun je relaties tussen collecties definiëren:

{
  "name": "categoryId",
  "type": "reference:categories",
  "required": true
}

Dit geeft aan dat categoryId verwijst naar een item in de collectie categories. Gebruik altijd namen die eindigen op -Id om duidelijk te maken dat het een verwijzing is naar een ander item.

Ontwerptips voor velden

1. Sla nooit overbodige data op Elk veld dat je toevoegt, komt terecht in de database én in elke API-respons. Voeg dus alleen velden toe die je daadwerkelijk nodig hebt — en waarvan je weet dat je ze gaat gebruiken in je app of frontend.

2. Gebruik default om gebruikersinput eenvoudiger te maken Als je weet dat een veld meestal dezelfde waarde heeft bij aanmaak (zoals status: "draft" of isActive: true), stel dan een standaardwaarde in en maak het veld niet verplicht. Daarmee voorkom je dat de gebruiker dit handmatig moet invullen en verklein je de kans op fouten of onvolledige data.

3. Beperk vrije tekst waar mogelijk Hoe meer je de gebruiker zelf laat invullen, hoe meer risico je loopt op inconsistente of vervuilde data. Gebruik bij voorkeur een beperkte set keuzewaarden door in de frontend te werken met checkboxes, radio-buttons of select-boxes waar mogelijk.

4. Gebruik áltijd validatie bij tekstvelden Bij string-velden zonder min of max bestaat de kans dat gebruikers lege waarden opslaan, of juist extreem lange invoer meesturen. Stel duidelijke grenzen in voor wat je verwacht — bijvoorbeeld een titel tussen de 5 en 100 tekens.

5. Kies voor duidelijke en consistente naamgeving Geef velden korte maar beschrijvende namen in het Engels en gebruik camelCase. Dus liever productName dan name_of_the_product of NaamProduct.

6. Bouw relaties bewust op met reference-velden Relaties maken je data krachtig, maar ze brengen ook complexiteit met zich mee. Gebruik reference alleen als je echt afhankelijk bent van data in een andere collectie — en geef het veld een duidelijke naam zoals categoryId of authorId.

7. Gebruik het juiste type — niet alleen het makkelijke type Een datum is geen string, en een boolean is geen number. Zorg dat je types aansluiten bij het soort data én de manier waarop je app ermee werkt. Dat voorkomt conversieproblemen in je frontend.