docs/12-schema-types
Wednesday 18 March 2026
Edit on Github

Schema.org Types for Social Applications

This document provides a comprehensive reference of Schema.org types commonly used in Mau social applications, with practical examples and usage patterns.

Table of Contents

  1. Overview
  2. Social Media Types
  3. Content Types
  4. Action Types
  5. Person and Organization
  6. Media Objects
  7. Events and Calendar
  8. Creative Works
  9. Custom Extensions
  10. Best Practices

Overview

What is Schema.org?

Schema.org is a collaborative vocabulary maintained by Google, Microsoft, Yahoo, and Yandex. It provides a structured way to describe entities on the web using JSON-LD.

Why Mau uses Schema.org:

  • Shared vocabulary - Universal understanding across applications
  • Well-documented - Extensive documentation and examples
  • Extensible - Add custom properties while maintaining compatibility
  • Web-compatible - Content can be understood by search engines and other web tools
  • Multilingual - Built-in support for multiple languages

JSON-LD Basics

Every Mau file follows this structure:

1{
2  "@context": "https://schema.org",
3  "@type": "TypeName",
4  "property1": "value1",
5  "property2": "value2"
6}

Required fields:

  • @context - Almost always "https://schema.org"
  • @type - Schema.org type (e.g., SocialMediaPosting, Article, Person)

Common optional fields:

  • @id - Unique identifier (URL) for this item
  • name - The name/title of the item
  • description - A short description
  • dateCreated / datePublished / dateModified - Timestamps
  • author - Person or Organization who created it

Social Media Types

SocialMediaPosting

Status updates, tweets, short posts, microblog entries.

Schema.org reference: SocialMediaPosting

Basic example:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "SocialMediaPosting",
 4  "@id": "/p2p/5d000b.../hello-world.json.pgp",
 5  "headline": "Hello, decentralized world!",
 6  "articleBody": "This is my first Mau post. Excited to be here!",
 7  "author": {
 8    "@type": "Person",
 9    "name": "Alice",
10    "identifier": "5d000b2f2c040a1675b49d7f0c7cb7dc36999d56"
11  },
12  "datePublished": "2026-03-18T01:00:00Z"
13}

Key properties:

  • headline - Short title or first line
  • articleBody - Main text content
  • author - Person who posted
  • datePublished - When it was posted
  • sharedContent - Link to content being shared (repost/retweet)
  • commentCount - Number of comments
  • interactionStatistic - Detailed interaction stats

With mentions:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "SocialMediaPosting",
 4  "headline": "Check out @bob's new project!",
 5  "mentions": [
 6    {
 7      "@type": "Person",
 8      "name": "Bob",
 9      "identifier": "a1234567890abcdef1234567890abcdef12345678"
10    }
11  ],
12  "datePublished": "2026-03-18T02:00:00Z"
13}

With hashtags:

1{
2  "@context": "https://schema.org",
3  "@type": "SocialMediaPosting",
4  "headline": "Building P2P apps with #mau #decentralization",
5  "keywords": ["mau", "decentralization", "p2p"],
6  "datePublished": "2026-03-18T03:00:00Z"
7}

Use cases:

  • Twitter-style status updates
  • Facebook posts
  • Mastodon toots
  • Any short-form social content

Comment

Comments, replies, discussions on content.

Schema.org reference: Comment

Basic example:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "Comment",
 4  "@id": "/p2p/a12345.../comment-1.json.pgp",
 5  "text": "Great post! Looking forward to more content.",
 6  "author": {
 7    "@type": "Person",
 8    "name": "Bob",
 9    "identifier": "a1234567890abcdef1234567890abcdef12345678"
10  },
11  "dateCreated": "2026-03-18T01:30:00Z",
12  "parentItem": {
13    "@type": "SocialMediaPosting",
14    "@id": "/p2p/5d000b.../hello-world.json.pgp"
15  }
16}

Key properties:

  • text - The comment content
  • parentItem - What’s being commented on (post, article, etc.)
  • author - Who wrote the comment
  • dateCreated - When it was posted
  • upvoteCount / downvoteCount - Vote counts

Nested replies (threaded comments):

 1{
 2  "@context": "https://schema.org",
 3  "@type": "Comment",
 4  "text": "I agree with Bob!",
 5  "parentItem": {
 6    "@type": "Comment",
 7    "@id": "/p2p/a12345.../comment-1.json.pgp"
 8  },
 9  "dateCreated": "2026-03-18T01:45:00Z"
10}

Use cases:

  • Reddit-style threaded comments
  • Blog comment sections
  • Discussion forums
  • Code review comments

Message

Private messages, direct messages, chat messages.

Schema.org reference: Message

Basic example:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "Message",
 4  "@id": "/p2p/5d000b.../msg-to-bob.json.pgp",
 5  "text": "Hey Bob, want to grab coffee tomorrow?",
 6  "sender": {
 7    "@type": "Person",
 8    "name": "Alice",
 9    "identifier": "5d000b2f2c040a1675b49d7f0c7cb7dc36999d56"
10  },
11  "recipient": {
12    "@type": "Person",
13    "name": "Bob",
14    "identifier": "a1234567890abcdef1234567890abcdef12345678"
15  },
16  "dateSent": "2026-03-18T10:00:00Z"
17}

Key properties:

  • text - Message content
  • sender - Who sent it
  • recipient - Who receives it (can be array for group chats)
  • dateSent - When sent
  • dateReceived - When received
  • dateRead - When read (read receipts)

Group chat:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "Message",
 4  "text": "Hey everyone! Meeting at 3 PM.",
 5  "sender": {
 6    "@type": "Person",
 7    "identifier": "5d000b..."
 8  },
 9  "recipient": [
10    { "@type": "Person", "identifier": "a12345..." },
11    { "@type": "Person", "identifier": "b67890..." },
12    { "@type": "Person", "identifier": "c11111..." }
13  ],
14  "dateSent": "2026-03-18T14:00:00Z"
15}

With attachments:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "Message",
 4  "text": "Here's the photo I mentioned",
 5  "messageAttachment": {
 6    "@type": "ImageObject",
 7    "contentUrl": "file:///home/user/.mau/5d000b.../photo-beach.jpg",
 8    "encodingFormat": "image/jpeg"
 9  },
10  "dateSent": "2026-03-18T15:00:00Z"
11}

Use cases:

  • WhatsApp-style messaging
  • Telegram direct messages
  • Slack DMs
  • End-to-end encrypted chat

Content Types

Article

Blog posts, long-form content, articles, essays.

Schema.org reference: Article

Basic example:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "Article",
 4  "@id": "/p2p/5d000b.../building-p2p-apps.json.pgp",
 5  "headline": "Building P2P Apps with Mau",
 6  "alternativeHeadline": "A Practical Guide to Decentralized Social Networks",
 7  "articleBody": "In this comprehensive guide, I'll walk you through...",
 8  "author": {
 9    "@type": "Person",
10    "name": "Alice",
11    "identifier": "5d000b..."
12  },
13  "datePublished": "2026-03-18T00:00:00Z",
14  "dateModified": "2026-03-18T12:00:00Z",
15  "wordCount": 2500,
16  "keywords": ["p2p", "mau", "decentralization", "tutorial"]
17}

Key properties:

  • headline - Main title
  • alternativeHeadline - Subtitle
  • articleBody - Full text content
  • author - Writer
  • datePublished - First published
  • dateModified - Last edited
  • wordCount - Length in words
  • keywords - Tags/categories
  • image - Featured image

With section structure:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "Article",
 4  "headline": "Complete Mau Tutorial",
 5  "articleBody": "...",
 6  "articleSection": "Technology",
 7  "hasPart": [
 8    {
 9      "@type": "WebPageElement",
10      "headline": "Introduction",
11      "text": "Mau is a p2p convention..."
12    },
13    {
14      "@type": "WebPageElement",
15      "headline": "Getting Started",
16      "text": "First, install the CLI..."
17    }
18  ],
19  "datePublished": "2026-03-18T00:00:00Z"
20}

Use cases:

  • Blog posts
  • News articles
  • Technical documentation
  • Long-form essays
  • Tutorials

BlogPosting

More specific type for blog entries (subtype of Article).

Schema.org reference: BlogPosting

Example:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "BlogPosting",
 4  "headline": "March 2026 Update",
 5  "articleBody": "This month I've been working on...",
 6  "author": {
 7    "@type": "Person",
 8    "name": "Alice"
 9  },
10  "datePublished": "2026-03-01T00:00:00Z",
11  "blogPost": true
12}

Use for: Traditional blog posts, personal journals, dev logs.

Note

Short notes, reminders, snippets (simpler than Article).

Schema.org reference: Note (under CreativeWork)

Example:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "Note",
 4  "text": "Remember to follow up with Bob about the project",
 5  "author": {
 6    "@type": "Person",
 7    "identifier": "5d000b..."
 8  },
 9  "dateCreated": "2026-03-18T09:00:00Z"
10}

Use cases:

  • Personal notes
  • Todo items
  • Reminders
  • Quick snippets

Recipe

Cooking recipes, instructions, ingredients.

Schema.org reference: Recipe

Example:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "Recipe",
 4  "@id": "/p2p/5d000b.../pasta-carbonara.json.pgp",
 5  "name": "Authentic Pasta Carbonara",
 6  "author": {
 7    "@type": "Person",
 8    "name": "Alice"
 9  },
10  "datePublished": "2026-03-15T00:00:00Z",
11  "image": {
12    "@type": "ImageObject",
13    "contentUrl": "file:///home/user/.mau/photos/carbonara.jpg"
14  },
15  "description": "Traditional Roman pasta dish with eggs, guanciale, and pecorino",
16  "prepTime": "PT10M",
17  "cookTime": "PT20M",
18  "totalTime": "PT30M",
19  "recipeYield": "4 servings",
20  "recipeCategory": "Main Course",
21  "recipeCuisine": "Italian",
22  "recipeIngredient": [
23    "400g spaghetti",
24    "200g guanciale (or pancetta)",
25    "4 large eggs",
26    "100g Pecorino Romano cheese, grated",
27    "Black pepper to taste",
28    "Salt for pasta water"
29  ],
30  "recipeInstructions": [
31    {
32      "@type": "HowToStep",
33      "text": "Bring a large pot of salted water to boil. Cook spaghetti according to package directions until al dente."
34    },
35    {
36      "@type": "HowToStep",
37      "text": "Cut guanciale into small cubes. Fry in a large pan over medium heat until crispy, about 5-7 minutes."
38    },
39    {
40      "@type": "HowToStep",
41      "text": "In a bowl, whisk eggs with grated Pecorino and plenty of black pepper."
42    },
43    {
44      "@type": "HowToStep",
45      "text": "Reserve 1 cup of pasta water, then drain pasta. Add pasta to the pan with guanciale (off heat)."
46    },
47    {
48      "@type": "HowToStep",
49      "text": "Pour egg mixture over pasta, tossing quickly. Add pasta water gradually to create a creamy sauce. The heat from pasta should cook the eggs without scrambling."
50    },
51    {
52      "@type": "HowToStep",
53      "text": "Serve immediately with extra Pecorino and black pepper."
54    }
55  ],
56  "nutrition": {
57    "@type": "NutritionInformation",
58    "calories": "650 calories",
59    "proteinContent": "28g",
60    "fatContent": "35g"
61  },
62  "aggregateRating": {
63    "@type": "AggregateRating",
64    "ratingValue": "4.8",
65    "reviewCount": "127"
66  }
67}

Use cases:

  • Recipe sharing apps
  • Cooking blogs
  • Food social networks
  • Community cookbooks

Action Types

Actions represent interactions users perform on content or with other users.

LikeAction

Likes, favorites, upvotes.

Schema.org reference: LikeAction

Example:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "LikeAction",
 4  "@id": "/p2p/a12345.../like-alice-post.json.pgp",
 5  "agent": {
 6    "@type": "Person",
 7    "name": "Bob",
 8    "identifier": "a1234567..."
 9  },
10  "object": {
11    "@type": "SocialMediaPosting",
12    "@id": "/p2p/5d000b.../hello-world.json.pgp"
13  },
14  "startTime": "2026-03-18T01:15:00Z"
15}

Key properties:

  • agent - Who performed the action (Person)
  • object - What was liked (any content type)
  • startTime - When the like happened
  • endTime - When unlike happened (optional)

Use cases:

  • Facebook likes
  • Twitter hearts
  • Reddit upvotes
  • Instagram likes

FollowAction

Following users, subscribing to content.

Schema.org reference: FollowAction

Example:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "FollowAction",
 4  "@id": "/p2p/a12345.../follow-alice.json.pgp",
 5  "agent": {
 6    "@type": "Person",
 7    "name": "Bob",
 8    "identifier": "a12345..."
 9  },
10  "object": {
11    "@type": "Person",
12    "name": "Alice",
13    "identifier": "5d000b..."
14  },
15  "startTime": "2026-03-18T10:00:00Z"
16}

Use cases:

  • Twitter following
  • Instagram following
  • RSS subscription equivalents
  • Friend connections

ShareAction

Sharing, reposting, retweeting content.

Schema.org reference: ShareAction

Example:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "ShareAction",
 4  "@id": "/p2p/a12345.../share-article.json.pgp",
 5  "agent": {
 6    "@type": "Person",
 7    "identifier": "a12345..."
 8  },
 9  "object": {
10    "@type": "Article",
11    "@id": "/p2p/5d000b.../building-p2p-apps.json.pgp"
12  },
13  "startTime": "2026-03-18T15:00:00Z",
14  "description": "This is an excellent tutorial!"
15}

Use cases:

  • Twitter retweets
  • Facebook shares
  • Reddit crossposts
  • Mastodon boosts

ReviewAction

Reviews, ratings, evaluations.

Schema.org reference: ReviewAction and Review

Example:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "Review",
 4  "@id": "/p2p/a12345.../review-recipe.json.pgp",
 5  "reviewBody": "Tried this recipe and it was amazing! Family loved it.",
 6  "reviewRating": {
 7    "@type": "Rating",
 8    "ratingValue": 5,
 9    "bestRating": 5
10  },
11  "author": {
12    "@type": "Person",
13    "name": "Bob",
14    "identifier": "a12345..."
15  },
16  "itemReviewed": {
17    "@type": "Recipe",
18    "@id": "/p2p/5d000b.../pasta-carbonara.json.pgp"
19  },
20  "datePublished": "2026-03-18T20:00:00Z"
21}

Use cases:

  • Product reviews
  • Movie/book reviews
  • Recipe ratings
  • Service reviews

ReplyAction

Formal reply to content (alternative to Comment).

Schema.org reference: ReplyAction

Example:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "ReplyAction",
 4  "agent": {
 5    "@type": "Person",
 6    "identifier": "a12345..."
 7  },
 8  "object": {
 9    "@type": "SocialMediaPosting",
10    "@id": "/p2p/5d000b.../post.json.pgp"
11  },
12  "result": {
13    "@type": "Comment",
14    "@id": "/p2p/a12345.../reply.json.pgp",
15    "text": "Great points!"
16  },
17  "startTime": "2026-03-18T16:00:00Z"
18}

Person and Organization

Person

Represents a user, author, contact.

Schema.org reference: Person

Profile example:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "Person",
 4  "@id": "/p2p/5d000b.../profile.json.pgp",
 5  "identifier": "5d000b2f2c040a1675b49d7f0c7cb7dc36999d56",
 6  "name": "Alice Smith",
 7  "givenName": "Alice",
 8  "familyName": "Smith",
 9  "email": "alice@example.com",
10  "url": "https://alice.example.com",
11  "image": {
12    "@type": "ImageObject",
13    "contentUrl": "file:///home/alice/.mau/avatar.jpg"
14  },
15  "description": "Software engineer, open source enthusiast, coffee lover",
16  "jobTitle": "Senior Developer",
17  "worksFor": {
18    "@type": "Organization",
19    "name": "Acme Corp"
20  },
21  "address": {
22    "@type": "PostalAddress",
23    "addressLocality": "San Francisco",
24    "addressRegion": "CA",
25    "addressCountry": "US"
26  },
27  "birthDate": "1990-05-15",
28  "sameAs": [
29    "https://twitter.com/alice",
30    "https://github.com/alice",
31    "https://linkedin.com/in/alice"
32  ]
33}

Key properties:

  • identifier - PGP fingerprint (primary key in Mau)
  • name - Full display name
  • email - Contact email
  • image - Profile picture
  • description - Bio
  • sameAs - Links to other profiles (social media)
  • url - Personal website

Minimal Person (in content):

1{
2  "@type": "Person",
3  "name": "Alice",
4  "identifier": "5d000b..."
5}

Organization

Companies, projects, groups.

Schema.org reference: Organization

Example:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "Organization",
 4  "name": "Mau Network",
 5  "url": "https://mau-network.org",
 6  "logo": {
 7    "@type": "ImageObject",
 8    "contentUrl": "https://mau-network.org/logo.png"
 9  },
10  "description": "Decentralized social networking protocol",
11  "foundingDate": "2024",
12  "founder": {
13    "@type": "Person",
14    "name": "Emad Elsaid"
15  },
16  "sameAs": [
17    "https://github.com/mau-network"
18  ]
19}

Media Objects

ImageObject

Photos, images, graphics.

Schema.org reference: ImageObject

Example:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "ImageObject",
 4  "@id": "/p2p/5d000b.../photo-sunset.json.pgp",
 5  "name": "Sunset at the Beach",
 6  "description": "Beautiful sunset I captured last weekend",
 7  "contentUrl": "file:///home/user/.mau/5d000b.../sunset.jpg",
 8  "encodingFormat": "image/jpeg",
 9  "width": "4000",
10  "height": "3000",
11  "fileSize": "2.5MB",
12  "creator": {
13    "@type": "Person",
14    "name": "Alice",
15    "identifier": "5d000b..."
16  },
17  "dateCreated": "2026-03-15T18:30:00Z",
18  "locationCreated": {
19    "@type": "Place",
20    "name": "Santa Cruz Beach"
21  },
22  "exifData": {
23    "@type": "PropertyValue",
24    "name": "Camera",
25    "value": "Canon EOS R5"
26  }
27}

Key properties:

  • contentUrl - Location of the image file
  • encodingFormat - MIME type (image/jpeg, image/png, etc.)
  • width / height - Dimensions in pixels
  • caption - Image caption
  • thumbnail - Smaller preview version
  • exifData - Camera metadata

VideoObject

Videos, movies, clips.

Schema.org reference: VideoObject

Example:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "VideoObject",
 4  "@id": "/p2p/5d000b.../tutorial-video.json.pgp",
 5  "name": "Mau Tutorial - Getting Started",
 6  "description": "Learn how to build your first Mau application",
 7  "contentUrl": "file:///home/user/.mau/5d000b.../tutorial.mp4",
 8  "thumbnailUrl": "file:///home/user/.mau/5d000b.../tutorial-thumb.jpg",
 9  "encodingFormat": "video/mp4",
10  "duration": "PT15M30S",
11  "width": "1920",
12  "height": "1080",
13  "uploadDate": "2026-03-18T00:00:00Z",
14  "creator": {
15    "@type": "Person",
16    "name": "Alice",
17    "identifier": "5d000b..."
18  }
19}

Duration format: ISO 8601 duration (PT15M30S = 15 minutes 30 seconds)

AudioObject

Music, podcasts, audio recordings.

Schema.org reference: AudioObject

Example:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "AudioObject",
 4  "name": "Podcast Episode 42: Decentralization",
 5  "description": "Discussion about P2P technologies and the future of social media",
 6  "contentUrl": "file:///home/user/.mau/5d000b.../podcast-ep42.mp3",
 7  "encodingFormat": "audio/mpeg",
 8  "duration": "PT1H23M45S",
 9  "datePublished": "2026-03-18T00:00:00Z"
10}

MediaObject

Generic media (when type is unclear or mixed).

Schema.org reference: MediaObject

Example:

1{
2  "@context": "https://schema.org",
3  "@type": "MediaObject",
4  "name": "Presentation Slides",
5  "contentUrl": "file:///home/user/.mau/5d000b.../slides.pdf",
6  "encodingFormat": "application/pdf"
7}

Events and Calendar

Event

Meetings, conferences, gatherings, appointments.

Schema.org reference: Event

Example:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "Event",
 4  "@id": "/p2p/5d000b.../mau-meetup.json.pgp",
 5  "name": "Mau Developer Meetup",
 6  "description": "Monthly gathering for Mau developers to discuss progress and ideas",
 7  "startDate": "2026-03-25T18:00:00Z",
 8  "endDate": "2026-03-25T20:00:00Z",
 9  "location": {
10    "@type": "Place",
11    "name": "Tech Hub",
12    "address": {
13      "@type": "PostalAddress",
14      "streetAddress": "123 Main St",
15      "addressLocality": "San Francisco",
16      "addressRegion": "CA",
17      "postalCode": "94102",
18      "addressCountry": "US"
19    }
20  },
21  "organizer": {
22    "@type": "Person",
23    "name": "Alice",
24    "identifier": "5d000b..."
25  },
26  "attendee": [
27    { "@type": "Person", "name": "Bob", "identifier": "a12345..." },
28    { "@type": "Person", "name": "Carol", "identifier": "c67890..." }
29  ],
30  "eventStatus": "https://schema.org/EventScheduled"
31}

Virtual event:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "Event",
 4  "name": "Online Webinar: Building with Mau",
 5  "startDate": "2026-03-20T15:00:00Z",
 6  "endDate": "2026-03-20T16:00:00Z",
 7  "location": {
 8    "@type": "VirtualLocation",
 9    "url": "https://meet.example.com/mau-webinar"
10  },
11  "eventAttendanceMode": "https://schema.org/OnlineEventAttendanceMode"
12}

Creative Works

Book

Books, eBooks, published works.

Schema.org reference: Book

Example:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "Book",
 4  "name": "The Decentralized Web",
 5  "author": {
 6    "@type": "Person",
 7    "name": "Alice Smith"
 8  },
 9  "isbn": "978-1234567890",
10  "datePublished": "2025-01-15",
11  "numberOfPages": 320,
12  "bookFormat": "https://schema.org/EBook",
13  "inLanguage": "en",
14  "publisher": {
15    "@type": "Organization",
16    "name": "Tech Press"
17  },
18  "description": "A comprehensive guide to building decentralized applications"
19}

MusicRecording

Songs, tracks, albums.

Schema.org reference: MusicRecording

Example:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "MusicRecording",
 4  "name": "Digital Freedom",
 5  "byArtist": {
 6    "@type": "Person",
 7    "name": "The P2P Band"
 8  },
 9  "inAlbum": {
10    "@type": "MusicAlbum",
11    "name": "Decentralized Dreams"
12  },
13  "duration": "PT3M45S",
14  "datePublished": "2026-01-01"
15}

SoftwareApplication

Software, apps, programs.

Schema.org reference: SoftwareApplication

Example:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "SoftwareApplication",
 4  "name": "Mau Desktop",
 5  "applicationCategory": "SocialNetworkingApplication",
 6  "operatingSystem": "Linux, macOS, Windows",
 7  "softwareVersion": "1.0.0",
 8  "datePublished": "2026-03-01",
 9  "author": {
10    "@type": "Person",
11    "name": "Alice"
12  },
13  "offers": {
14    "@type": "Offer",
15    "price": "0",
16    "priceCurrency": "USD"
17  }
18}

Custom Extensions

Extending Schema.org

You can add custom properties while maintaining Schema.org compatibility:

Method 1: Custom context

 1{
 2  "@context": [
 3    "https://schema.org",
 4    {
 5      "mau": "https://mau-network.org/vocab/",
 6      "replyCount": "mau:replyCount",
 7      "visibility": "mau:visibility",
 8      "encryptedFor": "mau:encryptedFor"
 9    }
10  ],
11  "@type": "SocialMediaPosting",
12  "headline": "Custom properties example",
13  "mau:replyCount": 15,
14  "mau:visibility": "friends-only",
15  "mau:encryptedFor": ["5d000b...", "a12345..."]
16}

Method 2: additionalProperty

 1{
 2  "@context": "https://schema.org",
 3  "@type": "SocialMediaPosting",
 4  "headline": "Post with metadata",
 5  "additionalProperty": [
 6    {
 7      "@type": "PropertyValue",
 8      "name": "clientApp",
 9      "value": "Mau Desktop 1.0"
10    },
11    {
12      "@type": "PropertyValue",
13      "name": "contentWarning",
14      "value": "spoilers"
15    }
16  ]
17}

Common custom properties for Mau:

  • visibility - public / friends / private / custom
  • encryptedFor - List of fingerprints
  • replyCount / likeCount / shareCount - Interaction stats
  • contentWarning - CW/trigger warnings
  • pinned - Whether post is pinned
  • editHistory - Links to previous versions

Best Practices

1. Always Include @context and @type

Good:

1{
2  "@context": "https://schema.org",
3  "@type": "SocialMediaPosting",
4  "headline": "Hello world"
5}

Bad:

1{
2  "headline": "Hello world"
3}

2. Use Appropriate Types

Choose the most specific type that fits your content:

  • Status update? Use SocialMediaPosting, not Article
  • Long blog post? Use Article or BlogPosting, not SocialMediaPosting
  • Private message? Use Message, not Comment

3. Include Timestamps

Always include creation/publication dates:

1{
2  "@type": "Article",
3  "headline": "My Post",
4  "datePublished": "2026-03-18T00:00:00Z",
5  "dateModified": "2026-03-18T12:00:00Z"
6}

Use ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ

4. Reference Other Content with @id

Link to other files using full paths:

1{
2  "@type": "Comment",
3  "text": "Great post!",
4  "parentItem": {
5    "@type": "SocialMediaPosting",
6    "@id": "/p2p/5d000b.../post.json.pgp"
7  }
8}

Don’t forget the .pgp extension in the @id!

5. Keep Person Objects Consistent

Always include the fingerprint as identifier:

1{
2  "@type": "Person",
3  "name": "Alice",
4  "identifier": "5d000b2f2c040a1675b49d7f0c7cb7dc36999d56"
5}

This allows clients to verify signatures and link content to the correct user.

6. Use Standard Vocabularies When Possible

Before creating custom properties, check if Schema.org already has what you need:

  • keywords instead of tags
  • dateModified instead of updatedAt
  • author instead of creator (for social content)

7. Support Multilingual Content

Use @language for internationalization:

 1{
 2  "@context": "https://schema.org",
 3  "@type": "Article",
 4  "headline": {
 5    "@value": "Hello World",
 6    "@language": "en"
 7  },
 8  "alternativeHeadline": [
 9    { "@value": "مرحبا بالعالم", "@language": "ar" },
10    { "@value": "Hola Mundo", "@language": "es" }
11  ]
12}

8. Validate Your JSON-LD

Test your content:

9. Document Custom Extensions

If you create custom properties, document them:

1## Custom Mau Properties
2
3- `mau:visibility` - String: "public" | "friends" | "private"
4- `mau:encryptedFor` - Array of strings: PGP fingerprints
5- `mau:replyCount` - Integer: Number of replies

Make your extension discoverable by publishing a vocabulary document.

10. Future-Proof Your Content

Schema.org evolves. Clients should:

  • Ignore unknown properties (forward compatibility)
  • Provide sensible defaults for missing properties
  • Validate required fields only

Write content that works even if schema changes.

Additional Resources

Official Documentation

Tools

Next Steps

Now that you understand Schema.org types:

  1. Build content - Create posts, articles, and messages
  2. Define your app’s types - Choose which types your application uses
  3. Extend when needed - Add custom properties for your use case
  4. Validate - Test your JSON-LD is correct

For implementation guidance, see API Reference (11-api-reference.md).

Questions? Check Troubleshooting (13-troubleshooting.md) or open an issue on GitHub.