Fideslang

https://ethyca.github.io/fideslang/
Admin
Fideslang is an open source privacy taxonomy and modeling language used to define and classify data...
Tokens:11,264
Snippets:104
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### System Manifest File

Source: https://ethyca.github.io/fideslang/resources/system

An example YAML manifest file for defining a system, located at /fides/demo_resources/demo_system.yml.

```yaml
system:
  - fides_key: demo_analytics_system
    name: Demo Analytics System
    description: A system used for analyzing customer behaviour.
    system_type: Service
    administrating_department: Engineering
    egress:
      - fides_key: another_demo_system
        type: system
        data_categories:
          - user.contact
    ingress:
      - fides_key: yet_another_demo_system
        type: system
        data_categories:
          - user.device.cookie_id
    privacy_declarations:
      - name: Analyze customer behaviour for improvements.
        data_categories:
          - user.contact
          - user.device.cookie_id
        data_use: improve.system
        data_subjects:
          - customer
        egress:
          - another_demo_system
        ingress:
          - yet_another_demo_system
```

--------------------------------

### Dataset Manifest File Example

Source: https://ethyca.github.io/fideslang/resources/dataset

An example of a YAML manifest file defining a dataset with collections and nested fields, including privacy data categories.

```yaml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
```

```yaml
dataset:
  - fides_key: demo_users_dataset
    name: Demo Users Dataset
    description: Data collected about users for our analytics system.
    collections:
      - name: users
        description: User information
        data_categories:
          - user
        fields:
          - name: first_name
            description: User's first name
            data_categories:
              - user.name
          - name: email
            description: User's Email
            data_categories:
              - user.contact.email
          - name: phone
            description: User's phone numbers
            data_categories:
              - user.contact.phone_number
            fields:
              - name: mobile
                description: User's mobile phone number
                data_categories:
                  - user.contact.phone_number
              - name: home
                description: User's home phone number
                data_categories:
                  - user.contact.phone_number
```

--------------------------------

### Organization manifest file example

Source: https://ethyca.github.io/fideslang/resources/organization

YAML manifest file defining an Organization with fides_key, name, description, security_policy, and contact arrays for controller, data protection officer, and representative.

```yaml
organization:
  fides_key: default_organization
  name: Acme Incorporated
  description: An Organization that represents all of Acme Inc.
  security_policy: https://example.org/privacy
  controller:
    name: Dave L. Epper
    address: 1 Acme Pl. New York, NY
    email: controller@acmeinc.com
    phone: +1 555 555 5555
  data_protection_officer:
    name: Preet Ector
    address: 1 Acme Pl. New York, NY
    email: dpo@acmeinc.com
    phone: +1 555 555 5555
  representative:
    name: Ann Othername
    address: 1 Acme Pl. New York, NY
    email: representative@acmeinc.com
    phone: +1 555 555 5555

```

--------------------------------

### Organization API payload example

Source: https://ethyca.github.io/fideslang/resources/organization

JSON payload for creating an Organization via API, with the same fields as the manifest file but in JSON format.

```json
{
  "fides_key": "default_organization",
  "name": "Acme Incorporated",
  "description": "An Organization that represents all of Acme Inc.",
  "security_policy": "https://example.org/privacy",
  "controller": {
    "name": "Dave L. Epper",
    "address": "1 Acme Pl. New York, NY",
    "email": "controller@acmeinc.com",
    "phone": "+1 555 555 5555"
  },
  "data_protection_officer": {
    "name": "Preet Ector",
    "address": "1 Acme Pl. New York, NY",
    "email": "dpo@acmeinc.com",
    "phone": "+1 555 555 5555"
  },
  "representative": {
    "name": "Ann Othername",
    "address": "1 Acme Pl. New York, NY",
    "email": "representative@acmeinc.com",
    "phone": "+1 555 555 5555"
  }
}

```

--------------------------------

### Declare a field with data categories in a dataset

Source: https://ethyca.github.io/fideslang/syntax

Shows a key-value example within a dataset, declaring a field named 'email' with a description and multiple data categories. The data_categories key accepts a list of values for multi-labeling.

```yaml
  fields:                           # Group of fields in the dataset.
    - name: email
      description: User's Email
      data_categories:              # Data category label(s) to assign field.
        - user.contact.email
        - user.account.contact.email
```

--------------------------------

### Policy manifest file (YAML)

Source: https://ethyca.github.io/fideslang/resources/policy

A YAML manifest file example for defining a Policy with a rule that rejects direct marketing. It uses the fides_key 'demo_privacy_policy' and includes data categories, uses, and subjects with 'ANY' match criteria.

```yaml
policy:
  - fides_key: demo_privacy_policy
    name: Demo Privacy Policy
    description: The main privacy policy for the organization.
    rules:
      - fides_key: reject_direct_marketing
        name: Reject Direct Marketing
        description: Disallow collecting any user contact info to use for marketing.
        data_categories:
          matches: ANY
          values:
            - user.contact
        data_uses:
          matches: ANY
          values:
            - advertising
        data_subjects:
          matches: ANY
          values:
            - customer
```

--------------------------------

### Declare a data category with dot notation

Source: https://ethyca.github.io/fideslang/syntax

Shows how to declare a data category for a user's contact information using dot notation. The comment indicates the category is about a given user.

```yaml
# This declares that the contact data is about a given user:
user.contact
```

--------------------------------

### System API Request Body

Source: https://ethyca.github.io/fideslang/resources/system

The JSON structure used for the POST /api/v1/system endpoint to create a new system.

```json
{
  "fides_key": "demo_analytics_system",
  "name": "Demo Analytics System",
  "description": "A system used for analyzing customer behaviour.",
  "system_type": "Service",
  "administrating_department": "Engineering",
  "egress": [
    {
      "fides_key": "another_demo_system",
      "type": "system",
      "data_categories": ["user.contact"]
    }
  ],
  "ingress": [
    {
      "fides_key": "yet_another_demo_system",
      "type": "system",
      "data_categories": ["user.device.cookie_id"]
    }
  ],
  "privacy_declarations": [
    {
      "name": "Analyze customer behaviour for improvements.",
      "data_categories": [
        "user.contact",
        "user.device.cookie_id"
      ],
      "data_use": "improve.system",
      "data_subjects": [
        "customer"
      ],
      "egress": ["another_demo_system"],
      "ingress": ["yet_another_demo_system"]
    }
  ]
}
```

--------------------------------

### System Hierarchy Representation

Source: https://ethyca.github.io/fideslang/resources/system

A visual representation of the system hierarchy within an organization.

```text
organization
  |-> ** system **
      |-> privacy declarations
```

--------------------------------

### Dataset Hierarchy Representation

Source: https://ethyca.github.io/fideslang/resources/dataset

A visual representation of the Dataset object hierarchy, showing the relationship between organization, system, dataset, collections, and fields.

```text
1
2
3
4
5
```

```text
organization
  |-> system
      |-> ** dataset **
          |-> collections
              |-> fields
```

--------------------------------

### Policy object structure

Source: https://ethyca.github.io/fideslang/resources/policy

A textual representation of the Policy object structure, showing that a Policy belongs to an Organization and contains rules.

```text
organization
  |-> ** policy **
      |-> rules
```

--------------------------------

### Declare a more specific data category with sub-category

Source: https://ethyca.github.io/fideslang/syntax

Shows how to declare a more specific data category for a phone number using dot notation with a sub-category. The comment explains the category is about a user, from the contact category, and of type phone number.

```yaml
# This declares that the is data about a given user,
# and is from the contact category and of type phone number.
user.contact.phone_number
```

--------------------------------

### Placeholder code block

Source: https://ethyca.github.io/fideslang/resources/policy

A placeholder code block that appears to be a placeholder for a diagram or structure representation. It contains only line numbers and no actual code.

```text
1
2
3
```

--------------------------------

### Policy API payload (JSON)

Source: https://ethyca.github.io/fideslang/resources/policy

A JSON payload for the POST /api/v1/policy endpoint, defining a policy with a rule that rejects direct marketing. It includes the organization_fides_key 'default_organization' and uses 'ANY' match criteria for data categories, uses, and subjects.

```json
{
  "fides_key": "demo_privacy_policy",
  "organization_fides_key": "default_organization",
  "name": "string",
  "description": "The main privacy policy for the organization.",
  "rules": [
    {
      "fides_key": "reject_direct_marketing",
      "organization_fides_key": "default_organization",
      "name": "Reject Direct Marketing",
      "description": "Disallow collecting any user contact info to use for marketing.",
      "data_categories": {
        "matches": "ANY",
        "values": [
          "user.contact"
        ]
      },
      "data_uses": {
        "matches": "ANY",
        "values": [
          "advertising"
        ]
      },
      "data_subjects": {
        "matches": "ANY",
        "values": [
          "customer"
        ]
      },
    }
  ]
}
```

--------------------------------

### Fideslang Dataset API Payload

Source: https://ethyca.github.io/fideslang/resources/dataset

A JSON object representing a dataset definition in Fideslang, including collections and nested field structures with associated data categories.

```json
{
    "fides_key": "demo_users_dataset",
    "name": "Demo Users Dataset",
    "description": "Data collected about users for our analytics system.",
    "collections": [
      {
        "name": "users",
        "description": "User information",
        "fields": [
          {
            "name": "first_name",
            "description": "User's first name",
            "data_categories": [
              "user.name"
            ]
          },
          {
            "name": "email",
            "description": "User's Email",
            "data_categories": [
              "user.contact.email"
            ]
          },
          {
            "name": "phone",
            "description": "User's phone numbers",
            "data_categories": [
              "user.contact.phone_number"
            ],
            "fields": [
              {
                "name": "mobile",
                "description": "User's mobile phone number",
                "data_categories": [
                  "user.contact.phone_number"
                ],
              },
              {
                "name": "home",
                "description": "User's home phone number",
                "data_categories": [
                  "user.contact.phone_number"
                ]
              }
            ]
          }
        ]
      }
    ]
  }
```
Tokens:
Raw