Audit Log Schemas Overview

Schema

A Schema describes what kinds of inputs are acceptable for a given action. Defining a Schema is recommended: it lets Edlink validate incoming Events and reject or flag data that does not conform.

Each Schema has a validation_level, which dictates what Edlink should do with non-conforming Events it receives:

• strict: non-conforming Events are rejected.
• lax: the default if unspecified. Non-conforming Events are accepted but flagged with a warning in the response to the Create Event call.

A Schema is created through the Create Schema endpoint, updated through the Update Schema endpoint, and retrieved through the Get Schema endpoint. Each Schema is versioned; every successful update closes the current version and returns a new UUID version.

Details about the properties available on a Schema available here.

Default actions and Schemas

It can be difficult to know what to track. To facilitate easy adoption of Audit Logs, Edlink pre-defines some common actions with their associated Schemas. All Schemas are set to lax for flexibility. Of course, your deep understanding of your own product will let you create new ones, or update these existing actions with Schemas that are more appropriate to your product's needs. However, we consider these a good starting point for developers:

• user.login
  • Schema:

  {
      "version": "00000000-0000-0000-0000-000000000000",
      "validation_level": "lax",
      "action": {
          "id": "user.login",
          "type": "create" // "creating" a session
      },
      "data": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "$id": "https://ed.link/api/default-schemas/user.login.json",
          "title": "user.login",
          "description": "An event describing a user logging into a client's application.",
          "type": "object",
          "properties": {
            "internal_user_id": {
              "description": "The unique identifier for a user in the client's application",
              "type": "string"
            },
            "application_name": {
              "description": "Name of the application the user is accessing",
              "type": "string"
            },
            "previous_login_date": {
              "description": "The timestamp of the user's last login",
              "type": "string"
            }
          },
          "required": [ "internal_user_id" ]
      }
  }
  

• user.logout
  • Schema:

  {
      "version": "00000000-0000-0000-0000-000000000000",
      "validation_level": "lax",
      "action": {
          "id": "user.logout",
          "type": "delete" // "deleting" a session
      },
      "data": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "$id": "https://ed.link/api/default-schemas/user.logout.json",
          "title": "user.logout",
          "description": "An event describing a user logging out of a client's application.",
          "type": "object",
          "properties": {
            "internal_user_id": {
              "description": "The unique identifier for a user in the client's application",
              "type": "string"
            },
            "application_name": {
              "description": "Name of the application the user is accessing",
              "type": "string"
            },
            "session_duration_ms": {
              "description": "The duration of the user's session in milliseconds",
              "type": "integer"
            }
          },
          "required": [ "internal_user_id" ]
      }
  }
  

• content.access
  • Schema:

  {
      "version": "00000000-0000-0000-0000-000000000000",
      "validation_level": "lax",
      "action": {
          "id": "content.access",
          "type": "read"
      },
      "data": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "$id": "https://ed.link/api/default-schemas/content.access.json",
          "title": "content.access",
          "description": "An event describing a user accessing some content within a client's application.",
          "type": "object",
          "properties": {
            "internal_user_id": {
              "description": "The unique identifier for a user in the client's application",
              "type": "string"
            },
            "application_name": {
              "description": "Name of the application the user is accessing",
              "type": "string"
            },
            "content_name": {
              "description": "The human-readable name of the content",
              "type": "string"
            },
            "content_type": {
              "description": "The internal type of the content (text, video, etc)",
              "type": "string"
            }
          },
          "required": [ "internal_user_id" ]
      }
  }