cognite_config.schema.json

{
    "$id": "cognite_config.schema.json",
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "description": "Configure connection to Cognite Data Fusion (CDF)",
    "properties": {
        "project": {
            "type": "string",
            "description": "CDF project to connect to."
        },
        "idp-authentication": {
            "type": "object",
            "description": "The `idp-authentication` section enables the extractor to authenticate to CDF using an external identity provider (IdP), such as Microsoft Entra ID (formerly Azure Active Directory).\nSee [OAuth 2.0 client credentials flow](https://learn.microsoft.com/en-us/entra/identity-platform/v2-oauth2-client-creds-grant-flow)",
            "properties": {
                "authority": {
                    "type": "string",
                    "default": "https://login.microsoftonline.com/",
                    "description": "AInsert the authority together with `tenant` to authenticate against Azure tenants."
                },
                "client-id": {
                    "type": "string",
                    "description": "Enter the service principal client id from the IdP."
                },
                "tenant": {
                    "type": "string",
                    "description": "Enter the Azure tenant."
                },
                "token-url": {
                    "type": "string",
                    "description": "Insert the URL to fetch tokens from."
                },
                "secret": {
                    "type": "string",
                    "description": "Enter the service principal client secret from the IdP."
                },
                "resource": {
                    "type": "string",
                    "description": "Resource parameter passed along with token requests."
                },
                "audience": {
                    "type": "string",
                    "description": "Audience parameter passed along with token requests."
                },
                "scopes": {
                    "oneOf": [
                        {
                            "type": "array",
                            "description": "Enter a list of scopes requested for the token",
                            "items": {
                                "type": "string",
                                "description": "A scope requested for the token",
                                "examples": [
                                    "https://api.cognitedata.com/.default"
                                ]
                            }
                        },
                        {
                            "type": "string",
                            "description": "Enter a space separated list of scopes requested for the token",
                            "examples": [
                                "https://api.cognitedata.com/.default"
                            ]
                        }
                    ]
                },
                "min-ttl": {
                    "type": "integer",
                    "default": 30,
                    "description": "Insert the minimum time in seconds a token will be valid. If the cached token expires in less than `min-ttl` seconds, it will be refreshed even if it is still valid."
                },
                "certificate": {
                    "type": "object",
                    "description": "Authenticate with a client certificate",
                    "unevaluatedProperties": false,
                    "required": [
                        "path"
                    ],
                    "properties": {
                        "authority-url": {
                            "type": "string",
                            "description": "Authentication authority URL"
                        },
                        "path": {
                            "type": "string",
                            "description": "Enter the path to the .pem or .pfx certificate to be used for authentication"
                        },
                        "password": {
                            "type": "string",
                            "description": "Enter the password for the key file, if it is encrypted."
                        }
                    }
                }
            },
            "oneOf": [
                {
                    "required": [
                        "tenant",
                        "secret"
                    ]
                },
                {
                    "required": [
                        "token-url",
                        "secret"
                    ]
                },
                {
                    "required": [
                        "certificate"
                    ]
                }
            ],
            "unevaluatedProperties": false,
            "required": [
                "client-id"
            ]
        },
        "host": {
            "type": "string",
            "default": "https://api.cognitedata.com",
            "description": "Insert the base URL of the CDF project."
        },
        "cdf-retries": {
            "type": "object",
            "description": "Configure automatic retries on requests to CDF.",
            "properties": {
                "timeout": {
                    "type": "integer",
                    "default": 80000,
                    "description": "Timeout in milliseconds for each individual request to CDF."
                },
                "max-retries": {
                    "type": "integer",
                    "default": 5,
                    "description": "Maximum number of retries on requests to CDF. If this is less than 0, retry forever."
                },
                "max-delay": {
                    "type": "integer",
                    "default": 5000,
                    "description": "Max delay in milliseconds between each retry. Base delay is calculated according to 125*2^retry milliseconds. If less than 0, there is no maximum."
                }
            },
            "unevaluatedProperties": false
        },
        "cdf-chunking": {
            "type": "object",
            "description": "Configure chunking of data on requests to CDF. Note that increasing these may cause requests to fail due to limits in the API itself",
            "properties": {
                "time-series": {
                    "type": "integer",
                    "default": 1000,
                    "description": "Maximum number of timeseries per get/create timeseries request",
                    "max": 1000,
                    "min": 1
                },
                "assets": {
                    "type": "integer",
                    "default": 1000,
                    "description": "Maximum number of assets per get/create assets request",
                    "max": 1000,
                    "min": 1
                },
                "data-point-time-series": {
                    "type": "integer",
                    "default": 10000,
                    "description": "Maximum number of timeseries per datapoint create request",
                    "max": 10000,
                    "min": 1
                },
                "data-point-delete": {
                    "type": "integer",
                    "default": 10000,
                    "description": "Maximum number of ranges per delete datapoints request",
                    "max": 10000,
                    "min": 1
                },
                "data-point-list": {
                    "type": "integer",
                    "default": 100,
                    "description": "Maximum number of timeseries per datapoint read request. Used when getting the first point in a timeseries.",
                    "max": 100,
                    "min": 1
                },
                "data-points": {
                    "type": "integer",
                    "default": 100000,
                    "description": "Maximum number of datapoints per datapoints create request",
                    "max": 100000,
                    "min": 1
                },
                "data-points-gzip-limit": {
                    "type": "integer",
                    "default": 5000,
                    "description": "Minimum number of datapoints in request to switch to using gzip. Set to -1 to disable, and 0 to always enable (not recommended). The minimum HTTP packet size is generally 1500 bytes, so this should never be set below 100 for numeric datapoints. Even for larger packages gzip is efficient enough that packages are compressed below 1500 bytes. At 5000 it is always a performance gain. It can be set lower if bandwidth is a major issue",
                    "max": 100000,
                    "min": 1
                },
                "raw-rows": {
                    "type": "integer",
                    "default": 10000,
                    "description": "Maximum number of rows per request to cdf raw",
                    "max": 10000,
                    "min": 1
                },
                "raw-rows-delete": {
                    "type": "integer",
                    "default": 1000,
                    "description": "Maximum number of row keys per delete request to raw",
                    "max": 1000,
                    "min": 1
                },
                "data-point-latest": {
                    "type": "integer",
                    "default": 100,
                    "description": "Maximum number of timeseries per datapoint read latest request",
                    "max": 100,
                    "min": 1
                },
                "events": {
                    "type": "integer",
                    "default": 1000,
                    "description": "Maximum number of events per get/create events request",
                    "max": 1000,
                    "min": 1
                },
                "sequences": {
                    "type": "integer",
                    "default": 1000,
                    "description": "Maximum number of sequences per get/create sequences request",
                    "max": 1000,
                    "min": 1
                },
                "sequence-row-sequences": {
                    "type": "integer",
                    "default": 1000,
                    "description": "Maximum number of sequences per create sequence rows request",
                    "max": 1000,
                    "min": 1
                },
                "sequence-rows": {
                    "type": "integer",
                    "default": 10000,
                    "description": "Maximum number of sequence rows per sequence when creating rows",
                    "max": 10000,
                    "min": 1
                },
                "instances": {
                    "type": "integer",
                    "default": 1000,
                    "description": "Maximum number of data modeling instances per get/create instance request",
                    "max": 1000,
                    "min": 1
                },
                "stream-records": {
                    "type": "integer",
                    "default": 1000,
                    "description": "Maximum number of stream records per get/create stream records request",
                    "max": 1000,
                    "min": 1
                }
            },
            "unevaluatedProperties": false
        },
        "cdf-throttling": {
            "type": "object",
            "description": "Configure the maximum number of parallel requests for different CDF resources.",
            "properties": {
                "time-series": {
                    "type": "integer",
                    "default": 5,
                    "description": "Maximum number of parallel requests per timeseries operation",
                    "min": 1
                },
                "assets": {
                    "type": "integer",
                    "default": 5,
                    "description": "Maximum number of parallel requests per assets operation",
                    "min": 1
                },
                "data-points": {
                    "type": "integer",
                    "default": 5,
                    "description": "Maximum number of parallel requests per datapoints operation",
                    "min": 1
                },
                "raw": {
                    "type": "integer",
                    "default": 5,
                    "description": "Maximum number of parallel requests per raw operation",
                    "min": 1
                },
                "ranges": {
                    "type": "integer",
                    "default": 5,
                    "description": "Maximum number of parallel requests per get first/last datapoint operation",
                    "min": 1
                },
                "events": {
                    "type": "integer",
                    "default": 5,
                    "description": "Maximum number of parallel requests per events operation",
                    "min": 1
                },
                "sequences": {
                    "type": "integer",
                    "default": 5,
                    "description": "Maximum number of parallel requests per sequences operation",
                    "min": 1
                },
                "instances": {
                    "type": "integer",
                    "default": 2,
                    "description": "Maximum number of parallel requests per data modeling instances operation",
                    "min": 1
                },
                "stream-records": {
                    "type": "integer",
                    "default": 4,
                    "description": "Maximum number of parallel requests per stream records operation",
                    "min": 1
                }
            },
            "unevaluatedProperties": false
        },
        "sdk-logging": {
            "type": "object",
            "description": "Configure logging of requests from the SDK",
            "properties": {
                "disable": {
                    "type": "boolean",
                    "description": "True to disable logging from the SDK, it is enabled by default"
                },
                "level": {
                    "type": "string",
                    "enum": [
                        "trace",
                        "debug",
                        "information",
                        "warning",
                        "error",
                        "critical",
                        "none"
                    ],
                    "default": "debug",
                    "description": "Log level to log messages from the SDK at"
                },
                "format": {
                    "type": "string",
                    "default": "CDF ({Message}): {HttpMethod} {Url} {ResponseHeader[X-Request-ID]} - {Elapsed} ms",
                    "description": "Format of the log message"
                }
            },
            "unevaluatedProperties": false
        },
        "nan-replacement": {
            "type": [
                "number",
                "null"
            ],
            "description": "Replacement for NaN values when writing to CDF. If left out, NaN values are skipped."
        },
        "extraction-pipeline": {
            "type": "object",
            "description": "Configure an associated extraction pipeline",
            "properties": {
                "external-id": {
                    "type": "string",
                    "description": "External ID of the extraction pipeline"
                },
                "frequency": {
                    "type": "integer",
                    "default": 600,
                    "description": "Frequency to report `Seen` to the extraction pipeline in seconds. Less than or equal to zero will not report automatically"
                }
            },
            "unevaluatedProperties": false
        },
        "certificates": {
            "type": "object",
            "description": "Configure special handling of SSL certificates. This should never be considered a permanent solution to certificate problems",
            "properties": {
                "accept-all": {
                    "type": "boolean",
                    "description": "Accept all remote SSL certificates. This introduces a severe risk of man-in-the-middle attacks"
                },
                "allow-list": {
                    "type": "array",
                    "description": "List of certificate thumbprints to automatically accept. This is a much smaller risk than accepting all certificates",
                    "items": {
                        "type": "string",
                        "description": "A certificate thumbprint to automatically accept, even if it is invalid or lacking a valid root certificate"
                    }
                }
            },
            "unevaluatedProperties": false
        }
    }
}