Documentation / Optional features

Document fields

Give each document typed values, such as its date, an amount, a client or a case number. Then filter your searches by them and list documents by them.

What document fields are

A document field is a typed value that Knovas keeps next to a document: the date of a letter, the total of an invoice, the client a file belongs to, a court case number. Because every value has a type, Knovas understands it. März 2024 is a month, CHF 1'234.50 is an amount in Swiss francs, and 4A 123/2024 is a case number of the Federal Supreme Court.

Values belong to a document identifier. If the same content was uploaded under two identifiers, each identifier keeps its own values, and a search result is returned under the identifier whose values match.

When it is off

Document fields and field filters are on by default. Knovas can still switch them off for an account, and an older Knovas release does not have them. While they are off, Knovas behaves exactly like an older server that does not know document fields:

Your field list

Each account has its own list of fields. The first time it is used, Knovas fills it with the core fields. Every field has a key such as document_date, labels in German, French, Italian and English (Dokumentdatum, Date du document, …) and other names (Datum). Requests may use any of them.

Look at your fields

curl --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem https://api.knovas.ch:8443/secured/graph/doc-fields

import requests

BASE = "https://api.knovas.ch:8443"
AUTH = dict(
    cert=("client_cert.pem", "client_key.pem"),  # your certificate and private key
    verify="ca_root_cert.pem",                   # Knovas' certificate
    timeout=60,
)

r = requests.get(f"{BASE}/secured/graph/doc-fields", **AUTH)
r.raise_for_status()
for field in r.json()["fields"]:
    print(field["key"], field["datatype"], field["labels"].get("de"), field["status"])

Add your own fields

curl -X POST https://api.knovas.ch:8443/secured/graph/doc-fields \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{
    "key": "cost_center",
    "datatype": "enum",
    "labels": {"de": "Kostenstelle", "fr": "Centre de coûts"},
    "aliases": ["KST"],
    "enum_values": [
      {"code": "4100", "labels": {"de": "Verwaltung"}},
      {"code": "4200", "labels": {"de": "Vertrieb"}}
    ]
  }'

import requests

BASE = "https://api.knovas.ch:8443"
AUTH = dict(
    cert=("client_cert.pem", "client_key.pem"),  # your certificate and private key
    verify="ca_root_cert.pem",                   # Knovas' certificate
    timeout=60,
)

r = requests.post(f"{BASE}/secured/graph/doc-fields", **AUTH, json={
    "key": "cost_center",
    "datatype": "enum",                    # a choice list
    "labels": {"de": "Kostenstelle", "fr": "Centre de coûts"},
    "aliases": ["KST"],                    # other names
    "enum_values": [
        {"code": "4100", "labels": {"de": "Verwaltung"}},
        {"code": "4200", "labels": {"de": "Vertrieb"}},
    ],
})
r.raise_for_status()                       # 201
print(r.json()["field"]["id"])

• An account can have up to 256 fields.
• Field keys, labels and other names are visible to everyone in your account. Knovas refuses ones that look like personal data, such as a person’s name, a date or a long number (422 key_looks_personal).
• Labels, other names and new choices can be added at any time with PATCH /secured/graph/doc-fields/<field id>. Settings that decide how values are read, such as the type or the code scheme, can only change in narrow cases, so choose them before you upload. A change that is no longer possible answers 409 field_type_locked.
• POST /secured/graph/doc-fields/<field id>/deprecate retires a field. Its values are kept, but it takes no new ones.

Packs

A pack is a ready-made set of fields. Two packs exist: core, which is installed automatically, and legal_ch for Swiss law firms (see the law firm example). Installing a pack copies its fields into your list. It never overwrites a field you already have, so installing twice is harmless.

# Which packs exist, and which are installed
curl --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem https://api.knovas.ch:8443/secured/graph/doc-fields/packs

# Install the Swiss legal pack
curl -X POST --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem https://api.knovas.ch:8443/secured/graph/doc-fields/packs/legal_ch/install

import requests

BASE = "https://api.knovas.ch:8443"
AUTH = dict(
    cert=("client_cert.pem", "client_key.pem"),  # your certificate and private key
    verify="ca_root_cert.pem",                   # Knovas' certificate
    timeout=60,
)

# Which packs exist, and which are installed
r = requests.get(f"{BASE}/secured/graph/doc-fields/packs", **AUTH)
for pack in r.json()["packs"]:
    print(pack["key"], pack["installed"])

# Install the Swiss legal pack
r = requests.post(f"{BASE}/secured/graph/doc-fields/packs/legal_ch/install", **AUTH)
r.raise_for_status()
print(r.json())   # {"installed": n, "skipped": m, "warnings": [...]}

Settings

# Read the settings
curl --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem https://api.knovas.ch:8443/secured/graph/doc-fields/settings

# Change them
curl -X PUT https://api.knovas.ch:8443/secured/graph/doc-fields/settings \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{"unknown_keys": "ignore", "date_order": "dmy"}'

import requests

BASE = "https://api.knovas.ch:8443"
AUTH = dict(
    cert=("client_cert.pem", "client_key.pem"),  # your certificate and private key
    verify="ca_root_cert.pem",                   # Knovas' certificate
    timeout=60,
)

# Read the settings
print(requests.get(f"{BASE}/secured/graph/doc-fields/settings", **AUTH).json())

# Change them
r = requests.put(f"{BASE}/secured/graph/doc-fields/settings", **AUTH, json={
    "unknown_keys": "ignore",
    "date_order": "dmy",
})
r.raise_for_status()

Who may change the field list

Every request of your account may read the field list, the packs and the settings. Changing them, and reading or changing folder defaults, is an administrator task. While access control is off for your account, any request may do it. Once it is on, the request must come from someone whose groups can see every document of your account, or who acts as your account’s administrator group. Anyone else gets 403 registry_write_requires_full_clearance.

Clients, courts and parties

An entity field names a knowledge-graph node that plays a role for the document: the client a file belongs to, the court of a case, the other party. The field says which node type its names refer to.

• Send a name ("Muster AG"), {"name": "Muster AG"} or {"node_id": "<node id>"}.
• Knovas links a name to a node when exactly one node of that type, among those you can see, carries that name or identifier. It ignores case, accents and spacing. The legal form may be left out only when the name stays unique, and Muster AG is never linked to Muster GmbH.
• Otherwise Knovas keeps the name as written, with the warning unresolved_entity or ambiguous_entity. Filters still find the document by that name. When you later create a node with exactly that name in that type, Knovas links the stored names in the background.
• Fields never create nodes. Deleting a node never deletes a value: the value stays under the name you wrote. A value you set only by node id has no name of yours, so after the node is deleted it shows as {"hidden": true} and is no longer found by name.
• A node id you cannot see is refused like an unknown one (invalid_value).
• party (core) and counterparty (legal_ch) refer to no node type, so their names always stay names.

Value formats

Write values the way your documents write them. Knovas stores them in one standard form, which is what you get back.

• Slash dates such as 03/04/2024 follow your account’s date order (day first by default) and come with the warning ambiguous_date when day and month could be swapped.
• Thousands: a single , or . before exactly three digits is read as the decimal mark in a number (1,234 is 1.234, with a warning). Write 1'234 for one thousand two hundred and thirty-four. In amounts with a currency, EUR 1.500 is one thousand five hundred.
• Several values: a field that holds several values takes a list of up to 32.
• Choice lists are found by any of their labels and other names, and clients and parties by their name regardless of case, accents and spacing. A text value is kept as written, so use a choice list or an entity field for anything you want to filter by name.

Access and privacy

• Access comes first. A document’s values are exactly as visible as the document. Searches and lists only find documents the user may see, and reading the values of a document the user may not see answers 404, as for an identifier that does not exist. Totals and technical details are only returned to a caller who may see every document of your account.
• Fields never restrict access. A field such as privileged is a marker. To decide who may see a document, use access groups.
• Held values. When an upload is stored as a duplicate of a document that has different access groups than the upload asked for, its title, description and fields are held back ("acl_mode": "quarantined"). Nobody sees them and they cannot be edited until the access settings agree, for example after you set the document’s access groups.
• No AHV numbers. Knovas refuses Swiss social security numbers (756.xxxx.xxxx.xx) in every field, however they are written (restricted_identifier).
• No personal data in field names. Field keys, labels and other names are visible to everyone in your account. Knovas refuses ones that look like personal data.
• Sensitive fields. Mark fields with special categories of personal data, such as health data, as "sensitivity": "special". "return_fields": true leaves them out: they are only returned when you name them.
• Values stay out of error messages. Errors and warnings name the key and its position, never the value.
• Used for filters only. Field values are not added to the search index. They take effect when you filter with where, list documents or show them.
• Deleting. Deleting a document deletes its title and values. Deleting all documents deletes all values and keeps your field list, settings and folder defaults.

Examples

Three typical setups. The names are placeholders.

Fiduciary (Treuhand)

A fiduciary keeps documents per client (Mandant) and business year. The core fields already cover document type, date, amount and period. Two fields of your own add the client, linked to your knowledge-graph nodes of the type Mandant, and a business year that runs from July to June:

# The client, linked to your knowledge-graph node type "Mandant"
curl -X POST https://api.knovas.ch:8443/secured/graph/doc-fields \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{"key": "mandant", "datatype": "entity_ref",
       "target_node_type_id": "<id of your node type Mandant>",
       "labels": {"de": "Mandant"}}'

# The business year: "GJ 2024" runs from 1 July 2024 to 30 June 2025
curl -X POST https://api.knovas.ch:8443/secured/graph/doc-fields \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{"key": "fiscal_year", "datatype": "period",
       "fy_start_month": 7, "fy_label": "start",
       "labels": {"de": "Geschäftsjahr", "fr": "Exercice", "en": "Business year"}}'

import requests

BASE = "https://api.knovas.ch:8443"
AUTH = dict(
    cert=("client_cert.pem", "client_key.pem"),  # your certificate and private key
    verify="ca_root_cert.pem",                   # Knovas' certificate
    timeout=60,
)

mandant_type_id = "<id of your node type Mandant>"   # see Knowledge graph, Node types

fields = [
    # The client, linked to your knowledge-graph node type "Mandant"
    {"key": "mandant", "datatype": "entity_ref",
     "target_node_type_id": mandant_type_id,
     "labels": {"de": "Mandant"}},
    # The business year: "GJ 2024" runs from 1 July 2024 to 30 June 2025
    {"key": "fiscal_year", "datatype": "period",
     "fy_start_month": 7, "fy_label": "start",
     "labels": {"de": "Geschäftsjahr", "fr": "Exercice", "en": "Business year"}},
]
for field in fields:
    r = requests.post(f"{BASE}/secured/graph/doc-fields", **AUTH, json=field)
    r.raise_for_status()
    print(r.json()["field"]["key"], r.json()["field"]["id"])

Uploads then carry "fields": {"mandant": "Muster AG", "fiscal_year": "GJ 2024", "doc_type": "Rechnung", "amount": "CHF 1'234.50"}, or the RemoteController fills mandant and fiscal_year from folders such as Muster AG/GJ 2024/. A search inside one client’s year:

curl -X POST https://api.knovas.ch:8443/secured/query \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{
    "Input": "Telefonkosten",
    "where": {"mandant": "Muster AG", "fiscal_year": "GJ 2024", "doc_type": "Rechnung"},
    "return_fields": ["document_date", "amount"]
  }'

import requests

BASE = "https://api.knovas.ch:8443"
AUTH = dict(
    cert=("client_cert.pem", "client_key.pem"),  # your certificate and private key
    verify="ca_root_cert.pem",                   # Knovas' certificate
    timeout=60,
)

r = requests.post(f"{BASE}/secured/query", **AUTH, json={
    "Input": "Telefonkosten",
    "where": {"mandant": "Muster AG", "fiscal_year": "GJ 2024", "doc_type": "Rechnung"},
    "return_fields": ["document_date", "amount"],
})
r.raise_for_status()
answer = r.json()
if not answer.get("where", {}).get("applied"):
    raise RuntimeError("The filter was not applied.")
for hit in answer["results"]:
    print(hit["pointer"], hit.get("fields", {}).get("amount"))

Law firm (Anwaltskanzlei)

The legal_ch pack adds the fields a Swiss law firm needs:

• client, matter and court, linked to your knowledge-graph nodes;
• counterparty;
• case_number in the formats of the Federal Supreme Court (4A_123/2024), the Federal Administrative Court, ECLI and cantonal courts such as Zurich (HG240017-O), with the other names Aktenzeichen and Geschäftsnummer;
• legal_class (Klage, Klageantwort, Replik, Urteil, Verfügung, Vollmacht, Gutachten, Honorarnote and more);
• filed_on, decision_date, deadline, legal_area and privileged.

client, matter and court link to your node types named Mandant, Mandat and Gericht (or Klient, Dossier, Tribunal and their other names). Create those node types before you install the pack. If none or several match, the field is installed without a node type and the answer warns target_type_missing:<key>. Install the pack as shown under Packs, then upload with fields such as "Aktenzeichen": "4A 123/2024", "client": "Muster AG", "counterparty": "Beispiel GmbH", "legal_class": "Klageantwort" and "filed_on": "2. Mai 2024". To list the documents of one case, newest filing first:

curl -X POST https://api.knovas.ch:8443/secured/graph/doc-values/find \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{
    "where": {"case_number": "4A 123/2024", "client": "Muster AG"},
    "sort": {"field": "filed_on", "order": "desc"},
    "return_fields": ["filed_on", "legal_class"]
  }'

import requests

BASE = "https://api.knovas.ch:8443"
AUTH = dict(
    cert=("client_cert.pem", "client_key.pem"),  # your certificate and private key
    verify="ca_root_cert.pem",                   # Knovas' certificate
    timeout=60,
)

body = {
    "where": {"case_number": "4A 123/2024", "client": "Muster AG"},
    "sort": {"field": "filed_on", "order": "desc"},
    "return_fields": ["filed_on", "legal_class"],
}
while True:
    r = requests.post(f"{BASE}/secured/graph/doc-values/find", **AUTH, json=body)
    r.raise_for_status()
    page = r.json()
    for doc in page["documents"]:
        print(doc.get("fields", {}).get("filed_on"), doc["title"])
    if page["next_after"] is None:
        break
    body["after"] = page["next_after"]

Medical practice (Arztpraxis)

There is no medical pack, so you create your own fields. Mark them as special and keep names out of them: use the patient number from your practice software, never a name or an AHV number. Restrict the documents themselves with access groups, for example a group for the doctors.

# A pseudonymous patient number
curl -X POST https://api.knovas.ch:8443/secured/graph/doc-fields \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{"key": "patient_ref", "datatype": "code", "sensitivity": "special",
       "labels": {"de": "Patientennummer"}}'

# Diagnoses as ICD-10-GM codes
curl -X POST https://api.knovas.ch:8443/secured/graph/doc-fields \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{"key": "diagnosis", "datatype": "code", "code_scheme": "icd10gm",
       "cardinality": "many", "sensitivity": "special",
       "labels": {"de": "Diagnose"}}'

import requests

BASE = "https://api.knovas.ch:8443"
AUTH = dict(
    cert=("client_cert.pem", "client_key.pem"),  # your certificate and private key
    verify="ca_root_cert.pem",                   # Knovas' certificate
    timeout=60,
)

fields = [
    # A pseudonymous patient number
    {"key": "patient_ref", "datatype": "code", "sensitivity": "special",
     "labels": {"de": "Patientennummer"}},
    # Diagnoses as ICD-10-GM codes
    {"key": "diagnosis", "datatype": "code", "code_scheme": "icd10gm",
     "cardinality": "many", "sensitivity": "special",
     "labels": {"de": "Diagnose"}},
]
for field in fields:
    requests.post(f"{BASE}/secured/graph/doc-fields", **AUTH, json=field).raise_for_status()

Uploads then carry "fields": {"patient_ref": "P-0042", "diagnosis": ["E1190"], "document_date": "12.09.2026", "doc_type": "Bericht"}. Knovas writes ICD-10-GM codes in their standard form (E1190 becomes E11.90), so a prefix finds a whole group of diagnoses:

curl -X POST https://api.knovas.ch:8443/secured/query \
  --cert client_cert.pem --key client_key.pem --cacert ca_root_cert.pem \
  -H "Content-Type: application/json" \
  -d '{
    "Input": "HbA1c Verlauf",
    "where": {"patient_ref": "P-0042", "diagnosis": {"prefix": "E11"}},
    "return_fields": ["document_date", "diagnosis"],
    "access_groups": ["Doctors"]
  }'

import requests

BASE = "https://api.knovas.ch:8443"
AUTH = dict(
    cert=("client_cert.pem", "client_key.pem"),  # your certificate and private key
    verify="ca_root_cert.pem",                   # Knovas' certificate
    timeout=60,
)

r = requests.post(f"{BASE}/secured/query", **AUTH, json={
    "Input": "HbA1c Verlauf",
    "where": {"patient_ref": "P-0042", "diagnosis": {"prefix": "E11"}},
    "return_fields": ["document_date", "diagnosis"],   # special fields only when named
    "access_groups": ["Doctors"],                      # the groups of the user who searches
})
r.raise_for_status()
answer = r.json()
if not answer.get("where", {}).get("applied"):
    raise RuntimeError("The filter was not applied.")
for hit in answer["results"]:
    print(hit["pointer"], hit.get("fields", {}).get("document_date"))

With the RemoteController

The RemoteController is the Knovas service that syncs documents from your folders, or from OneDrive and SharePoint, into Knovas. It can send fields with every upload. You usually set them in the Knovas Platform’s Ingestion tab, for each synced folder:

• All three end up in the upload layer. When one key gets values from several of them, the template wins, then the fixed value, then the file property. Your manual edits win over all three, and folder defaults at Knovas come below them.
• The RemoteController reads the fields answer of every upload. While Document fields is off for your account, it indexes documents exactly as before and reports the fields as not accepted. Once Knovas enables the feature, it sends those documents again, a limited number per cycle.
• If Knovas refuses an upload because of its fields, the RemoteController sends it again once without fields, so the document is still indexed.
• Changing a folder’s fields uploads all of its documents again, with full text extraction, and each upload is billed. By default at most 100 documents are sent again per cycle, so 20,000 documents on a nightly schedule take about three nights or more. For a value that does not depend on the folder, use a folder default at Knovas instead: it needs no upload.
• A file’s modification date never becomes its document date.
• Renaming or moving a file makes it a new document at Knovas. Values you edited on the old one are not carried over.

In the Knovas Platform

The Knovas Platform is the search web app for your account. It asks Knovas what your account supports and shows only that. Without Document fields it looks and works exactly as before.

• Results count as filtered only when Knovas confirms the filter. Otherwise the Platform shows no results and offers a button to search without the filter. It never drops a filter on its own.
• Fields marked special (besonders schützenswert) never appear on result cards, get no name suggestions, and only administrators may edit them.
• A list sorted by a deadline field says that it is no deadline control.

What document fields do not do

These are not part of Knovas 1.5.0:

• Counting documents per value (facets).
• Editing many documents at once. Each edit changes one document; for whole folders, use folder defaults.
• Reading values from the document text, or suggesting values. Values come from uploads, your edits and folder defaults only.
• Packs other than core and legal_ch.
• Tracking deadlines or sending reminders.
• Narrowing a search by a value that is only mentioned in the question. To find “invoices from 2024”, send where.
• Filtering template filling by fields.
• Path templates at Knovas. Folder defaults are fixed values per prefix; templates such as {mandant}/** are read by the RemoteController.

Questions? Write to contact@knovas.ch.

This page describes Knovas 1.5.0. Last updated 3 October 2026.