Traits and behaviors

[ngerakines]

A while ago, there was a discussion about "traits" as a lexicon concept. A trait would define a number of fields and if a record had those fields, it was "implementing" that trait or behavior.

For example, if a record has the fields "name", "text", "startsAt", and "endsAt" then the "Event" trait is applicable.

Rationale

Traits can be a useful tool for determining how something can be treated within applications. For example, Smoke Signal, could consider any record that validates against the "Event" trait as something that could be viewed or RSVP'd to.

The same could apply to views. With the trait "FacetedView" including "createdAt", "text", and "facets", any record that matches the trait could be displayed within an app view. This would be a huge shift in how app views like bsky.app treat static types like posts as the only things that can be displayed.

Schema

A trait is a new lexicon "type" of "trait". Only objects have traits and traits only apply to objects.

A "trait" lexicon type has the following attributes:

• type - must be "object"
• description (optional)
• trait - a lexicon "object" that defines the trait

Example Trait

{
    "lexicon": 1,
    "id": "community.lexicon.traits.event",
    "defs": {
        "main": {
            "type": "trait",
            "description": "Fields associated with Events",
            "trait": {
                "type": "object",
                "required": [
                    "name",
                    "text",
                    "startsAt",
                    "endsAt"
                ],
                "properties": {
                    "name": {
                        "type": "string",
                        "maxLength": 100,
                        "description": "The name of the event."
                    },
                    "text": {
                        "type": "string",
                        "maxLength": 3000,
                        "description": "The event description and content for the event."
                    },
                    "startsAt": {
                        "type": "string",
                        "format": "datetime",
                        "description": "Client-declared timestamp when this event starts."
                    },
                    "endsAt": {
                        "type": "string",
                        "format": "datetime",
                        "description": "Client-declared timestamp when this event ends."
                    }
                }
            }
        }
    }
}

[Hoid]

Wouldn't traits have to be able to predict the exact field names that lexicons use? For example, if an events service used startTime instead of startsAt, that lexicon wouldn't have this trait of community.lexicon.traits.event applied, right?

Also, unless I'm misunderstanding, why would you stipulate the specific maxLength and description values? Wouldn't those have to match as well, meaning an even higher likelihood that individual lexicons wouldn't have this trait applied?

[ngerakines]

Full disclosure: I copied and pasted parts of that JSON content from another thread for events.

I could see use cases for traits to have their own, optional constraints that further constrain field types as it applies to records. For example, would it lead to a different behavior or user interaction if the current bsky.app AppView had a post type with a maxLength of 300, while the whtwnd post type has one of 5000, but the bsky.app AppView could display anything that implements the trait with a trait-imposed maxLength limit of 500 for display / UX purpose?

Alternatively, I could see value in traits being simply field type constraints, imposing basic validation of field presence, "type", and format.

[ebwinters]

How would this be ingested from a firehose or a jetstream connection? Let's say smoke signal has some ingestor listening to smokesignal.* events from the firehose with filterCollections: [smokesignal...]. But now the smokesignal app wants to ingest events that implement the event trait. There would be no way to automatically pick up those events unless we know the exact NSID whoever implements the event trait.

[ebwinters]

Furthermore how do you know that if I decide to publish a new schema it will implement a trait? Is there some sort of validation before I publish the event to the atmosphere? I have some new schema EthansEvent that I say implements trait event but in reality it does not. How would you envision a consumer would know this without deserializing each event and running a manual validation?

[ngerakines]

That's an important distinction with traits and interfaces. The record itself doesn't say that it is conforming to a given interface / trait. It is entirely up to the consumer to validate an event against a given trait to make that determination.

Consider this trait:

{
    "lexicon": 1,
    "id": "community.lexicon.traits.plain",
    "defs": {
        "main": {
            "type": "trait",
            "trait": {
                "type": "object",
                "required": ["text"],
                "properties": {
                    "name": {"type": "string"},
                    "text": {"type": "string"}
                }
            }
        }
    }
}

And these records:

{
    "$type": "app.bsky.feed.post",
    "createdAt": "2024-12-02T19:28:30.450Z",
    "text": "Alright, in my defense, most of it was spam."
}

{
    "$type": "app.bsky.feed.posts",
    "createdAt": "2024-12-02T19:28:30.450Z",
    "text": ["Alright, in my defense, most of it was spam."]
}

Only the first would satisfy the criteria of the trait. Neither of them say they implement (or even are aware) of the trait. The developer(s) that are responsible for the first (app.bsky.feed.post) may know of the trait and it may inform the way they design their lexicon.

[ebwinters]

I see - thanks for the detailed explanation. Very helpful

So back to the first point. If traits are implemented, and we want to support them during ingestion, it is either on

1. The consuming app to subscribe to all events (whereas before maybe had a collection filter) and run validation on each event
2. Contribute to firehose/jetstream to add logic in those 2 libraries that support trait filtering - which might be too much load on the relay tbh

[tom-sherman]

This is a really useful discussion thread that clarifies a few things for me.

Just because traits don't exist "at runtime" doesn't mean they're not helpful for pre-filtering the firehose. Trait resolution becomes a discovery mechanism (at Dev time, not at runtime) for the collections that you want to filter for.

[verdverm]

This reminds me a lot of Go interfaces, if it walks like a duck and talks like a duck...

With Lexicon going on-protocol as records, it would seem feasible to build an index and querying service to know what lexicon implement what traits (or interfaces in Go speak)

[DavidBuchanan314]

The description here talks about validating whether a record implements some trait, but imho it makes more sense to validate whether a lexicon implements some trait.

From looking at a record alone, you can't infer the full type information of its fields (e.g. is something a string field that happens to contain an at:// URI, or is it actually typed as an at-uri string?), and so record-based trait checks can't be 100% certain.

[maxfzz]

I think explicitly extending the behavior of Lexicon types rather then implicitly inferring the behavior based on field names would be more useful, letting Lexicon developers inherit common properties and customize their restrictions for application-specific usage.

In this example, I'm using two non-standard Lexicon features, so I'll explain them separately:

1. Declaring the community.lexicon.actor.profile#main type as a union of other record types should indicate to the PDS that it is acceptable for the other record types to be saved under the community.lexicon.actor.profile collection, despite their $type field not being exactly equal to community.lexicon.actor.profile.
2. Declaring the profile types as "extending" the #com.atproto profile type should indicate to Lexicon consumers that the types inherit all the properties and associated restrictions of the #com.atproto type, unless specifically overridden by the type's Lexicon. This is the feature I am proposing in this comment.

The restrictions applied to #com.atproto are given as example values to showcase overriding restrictions, and not intended for actual specification.

{
  "lexicon": 1,
  "id": "community.lexicon.actor.profile",
  "defs": {
    "main": {
      "type": "union",
      "closed": false,
      "refs": [
        "#app.bsky",
        "#com.atproto",
        "#community.lexicon.calendar"
      ]
    },
    "app.bsky": {
      "type": "record",
      "extends": ["#com.atproto"],
      "record": {
        "type": "object",
        "properties": {
          "displayName": {
            "maxLength": 640,
            "maxGraphemes": 64
          },
          "description": {
            "maxLength": 2560,
            "maxGraphemes": 256
          },
          "joinedViaStarterPack": { "type": "ref", "ref": "com.atproto.repo.strongRef" },
          "pinnedPost": { "type": "ref", "ref": "com.atproto.repo.strongRef" }
        }
      }
    },
    "com.atproto": {
      "type": "record",
      "record": {
        "type": "object",
        "properties": {
          "displayName": {
            "type": "string",
            "maxLength": 800,
            "maxGraphemes": 80
          },
          "description": {
            "type": "string",
            "maxLength": 5120,
            "maxGraphemes": 512
          },
          "avatar": { "type": "blob", "accept": ["image/*"], "maxSize": 1000000 },
          "banner": { "type": "blob", "accept": ["image/*"], "maxSize": 1000000 }
        }
      }
    },
    "community.lexicon.calendar": {
      "type": "record",
      "extends": ["#com.atproto"],
      "record": {
        "type": "object",
        "properties": {
          "tz": { "type": "string" }
        }
      }
    }
  }
}

[ngerakines]

The description here talks about validating whether a record implements some trait, but imho it makes more sense to validate whether a lexicon implements some trait.

From looking at a record alone, you can't infer the full type information of its fields (e.g. is something a string field that happens to contain an at:// URI, or is it actually typed as an at-uri string?), and so record-based trait checks can't be 100% certain.

Yeah, I think traits answering "does or does" apply to a record creates the least amount of work when encountering new types.

Consider the trait displaysAsText

{
    "lexicon": 1,
    "id": "community.lexicon.traits.displaysAsText",
    "defs": {
        "main": {
            "type": "trait",
            "trait": {
                "type": "object",
                "required": ["createdAt", "text"],
                "properties": {
                    "createdAt": {"type": "string"},
                    "text": {"type": "string"}
                }
            }
        }
    }
}

An application developer may know about common record types like:

{
    "$type": "app.bsky.feed.post",
    "createdAt": "2024-12-02T19:28:30.450Z",
    "text": "Alright, in my defense, most of it was spam."
}

What if a new record comes in that looks like this:

{
    "$type": "ai.llm.prompt",
    "createdAt": "2024-12-02T19:28:30.450Z",
    "text": "You are a helpful assistant. Answer the following question politely: How do I bluesky?"
}

Your application doesn't need to know the record type or understand it's intent. You can simple compare it to the trait and know that it can be displayed as plain text.

The alternative is to perform lookups that could fail or leak that your application is evaluating the record.

[ngerakines]

I think explicitly extending the behavior of Lexicon types rather then implicitly inferring the behavior based on field names would be more useful, letting Lexicon developers inherit common properties and customize their restrictions for application-specific usage.

That creates a requirement that types and traits have knowledge of the other beforehand.

[maxfzz]

I think explicitly extending the behavior of Lexicon types rather then implicitly inferring the behavior based on field names would be more useful, letting Lexicon developers inherit common properties and customize their restrictions for application-specific usage.

That creates a requirement that types and traits have knowledge of the other beforehand.

There's a place for both methodologies in the Lexicon specification; implicit/consumer-side and explicit/producer-side behavior inheritance.