
## The JSON Schema documentation project

The main goal of JSON Schema's [documentation project](https://github.com/orgs/json-schema-org/discussions/687) is to create a scalable documentation architecture that is clear, consistent, and comprehensive. To achieve this through Google Season of Docs (GSoD), we focused on:

- **[Restructuring the specification docs](https://github.com/json-schema-org/website/pull/823)**: The specification docs need a structure that helps all [personas](https://github.com/json-schema-org/community/issues/336#personas) understand how JSON Schema has evolved across different releases and the features introduced in each version.
- **[Revamping the information architecture](https://github.com/json-schema-org/website/issues/790)**: The documentation needs a new information architecture that better aligns with the [documentation developer journey](https://www.figma.com/board/TRjQUw33K93y8RlJMSRkJs/JSON-dev-journey?node-id=0-1&t=fF2pJ8IwpJvbFzDU-1) and organizes content based on the [diataxis framework](https://diataxis.fr/). The new information architecture's goal is to improve the onboarding experience and content findability.

## The GSoD project accomplishments

Since May, the team ([Valeria Hernandez](https://www.linkedin.com/in/valeriahhdez/), [Blessing Ene Anyebe](https://www.linkedin.com/in/anyebe-blessing-ene-kwennb/), [Dhairya Amrish Majmudar](https://www.linkedin.com/in/dhairya-majmudar/), and [Benjamin Granados](https://www.linkedin.com/in/benjagranados/)) has been working hard to achieve these goals. On the part of documentation, we have completed the following: 

- Conducted a thorough content audit
- Mapped out the [developer experience journey](<(https://www.figma.com/board/TRjQUw33K93y8RlJMSRkJs/JSON-dev-journey?node-id=0-1&t=gYkdGtHk2sKrCQM0-0)>)
- Implemented the [keywords page](https://json-schema.org/understanding-json-schema/keywords)
- Restructured the [specification docs](https://github.com/json-schema-org/website/pull/823)

The team has also introduced changes to the website, like a table of contents and a [Next-Previous](https://github.com/json-schema-org/website/pull/807) component that aim to improve content scannability and navigation. 

## The road ahead

So, what's pending? We're currently working on the [JSON Hyper-Schema](https://github.com/json-schema-org/website/issues/896) and [Migration pages](https://github.com/json-schema-org/website/issues/897), which are part of the specification docs. 

We're also documenting [guidelines for docs contributions and text formatting](https://github.com/json-schema-org/website/pull/902), documenting missing keywords (see issues [951](https://github.com/json-schema-org/website/issues/951), [952](https://github.com/json-schema-org/website/issues/952), and [961](https://github.com/json-schema-org/website/issues/961)), and writing step-by-step guides (see issues [180](https://github.com/json-schema-org/website/issues/180), [950](https://github.com/json-schema-org/website/issues/950), and [954](https://github.com/json-schema-org/website/issues/954)). 

## Conclusion

Our documentation efforts are expanding daily, and your contributions can improve them. There are several ways you can help, including:

- Breaking down large documents to improve the overall structure of the documentation website
- Creating missing documentation for the Troubleshooting and Scaling stages of the developer journey
- Contributing to the Migration page

Our docs meeting is held bi-weekly every Tuesday at 3:00 PM (UTC). You're welcome to join the #gsod24 channel in the JSON Schema [Slack workspace](https://json-schema.org/slack) and send us a message with your email address so we can add you to the meeting.

We appreciate your interest in the JSON Schema documentation project and look forward to your contributions and their benefits to the wider developer community.

**The JSON Schema's Google Season of Docs Team.**

Photo by <a href="https://unsplash.com/@miinyuii?utm_content=creditCopyText&utm_medium=referral&utm_source=unsplash">Duy Pham</a> on <a href="https://unsplash.com/photos/people-holding-shoulders-sitting-on-wall-Cecb0_8Hx-o?utm_content=creditCopyText&utm_medium=referral&utm_source=unsplash">Unsplash</a>
  

Blessing Ene Anyebe

Valeria Hernandez

Dhairya Amrish Majmudar

Benjamin Granados

Update from the Google Season of Docs 2024 Project


## Ambassadors program?

You may have noticed our new Ambassadors Program! If not, don't worry—we're here to explain what it is and how you can get involved.

I'm personally very excited to see this program come to life. Recognizing our community champions in a meaningful and sustainable way has always been a goal. The Ambassadors Program is our first step in publicly supporting our most experienced and helpful members.

We have many community members who frequently help others, provide feedback, answer questions, and debug schemas and code. They also assist newcomers in avoiding basic misconceptions. JSON Schema wouldn't be where it is today without this support.

## The time is right - we are growing

For the past few years, a small team has worked full time on JSON Schema, focusing on ongoing projects. Now, we have the capacity to launch new initiatives, including this Ambassadors Program. We want to better recognize and support those who are giving back to our community.

We are better placed today than we ever have been to support and empower our existing ambassadors, and build a program which recognizes and supports them to further their efforts. It's always encouraging to see others as excited about JSON Schema as you are.

<Regularquote>
  _"The new website, and assorted outreach programmes have started to connect the huge JSON Schema user base, and we've really started to see the benefit in terms of the number of people actively participating." - **Matthew Adams** - Founder at [Endjin](https://endjin.com) - Candidate Ambassador._
</Regularquote>

## How we benefit, from today

When thinking about our programs, two aspects we should consider are how they will impact the project overall, and the community. These are not the only aspects, but ones I want to touch on in this context.

### As a Project

Having ambassadors not only recognizes individual contributions but also benefits JSON Schema. It will increase visibility and encourage positive community engagement.

Despite JSON Schema's presence, many still see it as part of another standard. By promoting JSON Schema through various channels, we enhance its recognition and usage. This increased visibility can attract more sponsorships, funding further programs like the Ambassadors Program and fostering a better ecosystem. It's a positive cycle; once we start, momentum will help us grow.

As the project thrives, so too does our community. The Ambassadors Program brings several benefits specifically for our community.

<Regularquote>
  _"The community is very friendly, welcoming, and extremely smart. I already learnt a LOT by participating in it. I want the JSON Schema ecosystem to grow, as it will likely power my business as a result. The Ambassadors Program is a great opportunity to recognise key contributors and encourage them to continue being involved." - **Juan Cruz Viotti** - Founder and CTO at [Intelligence.AI](https://intelligence.ai) - Candidate Ambassador_
</Regularquote>

### As the Community

The project and the community both benefit from the Ambassadors Program. Ambassadors will contribute valuable content, enhancing learning and engagement. To keep their ambassador status each year, ambassadors will be expected to make a number of contributions that benefit the community, such as articles, videos, podcasts, or even talking or running a workshop at a conference.

Given the prominence of the ambassadors, we will, collectively, check any and all published work they produce, making sure it's accurate. If you work with code, you've probably seen your fair share of poorly documented projects, and you know the impact that can have. High-quality, up-to-date content makes it easier for both newcomers and veterans to learn and stay current.

Further, we don't require or even expect that all the content ambassadors produce will go onto the project's website. No. There's actually improved reach by ambassadors using their existing channels to reach their community, hopefully expanding the JSON Schema community in addition to educating other spaces.

## A portrait of an Ambassador

We've long planned the Ambassadors Program and have identified initial candidates. (You can nominate yourself or others!) Here are the qualities we seek in ambassadors.

Firstly, an ambassador has to be with the community. This means in the slack server, on Github, and occasionally on calls or other places representing or being a recognised expert or source of knowledge for JSON Schema.

Critically, we expect ambassadors to be aligned with the JSON Schema project's mission and values, be respectful of our code of conduct, and continue to be active in the community.

## Recognising our Ambassadors from the community

We easily identified several community members to invite into the Ambassadors Program. The TSC and the Community Team spend a LOT of time in our community spaces, so even if we don't always reply or comment, we do notice those who are active and helpful.

When I first started the JSON Schema Slack server, the numbers were very few. Gradually, it grew. The core team answered most of the questions. I recall the feeling when I came back in the morning to find other people had answered questions from the community while I'd been asleep. I've previously [recognised](https://words.benhutton.me/2023-05-23-two-words-big-win) that saying "thank you" can be a big win, but I also know that we can do several magnitudes better.

We already have several members of our community who have become ambassadors for JSON Schema, just without any sort of formal recognition. Recognising, supporting, and further enabling these individuals, and new ambassadors, is going to have a positive impact, and I can't wait to see what it unlocks for JSON Schema in the future.

There's a swag kit for all accepted into the Ambassadors Program, and I can't wait to meet the individuals excited and proud to be wearing the exclusive swag at events and conferences in the future. We see you, ambassadors!

## How to apply today

OK, OK. If you've read all the above, maybe you haven't yet made it to the [Ambassador Program documentation](https://json-schema.org/ambassadors) file in our community repo. That would be your next stop if you're thinking about applying to become an ambassador.

We will be looking for existing contributions from individuals who have already been in our community for a while. If you're brand new to JSON Schema, becoming an ambassador is probably not something immediately in your reach, and that's OK. If you have some experience with JSON Schema, go write about it, apply to talk at events and conferences, or make videos. Be part of our community, answer questions. Then your application is much more likely to be accepted.

As I mentioned, we have a number of people in mind already, and I'd love to introduce a few of them to you today. If you're in our community spaces, you've probably seen them around.

"As a small team ourselves at Endjin, we live by the mantra 'helping small teams achieve big things'. I believe we can have a disproportionate positive impact by working on JSON Schema as it is so widely adopted, across so many different disciplines and industry verticals." - Matthew Adams

"JSON is the world's most popular data format, and it's impossible to not work with it in some way or another. Once you want to embrace JSON, JSON Schema is the most powerful and expressive schema language for it, elegantly enabling a wide variety of use cases." - Juan Cruz Viotti

## You (yes, you!) can help support and expand Ambassadors and other programs

If this program sounds great and you want to support it, you can! Being part of our community is a great first step. Our Slack server may sometimes get busy, but you could mute it and only get notified of announcements, if you wanted. We actively use and monitor GitHub Discussions, so if Slack isn't your thing or you have one too many already, that's going to be a space for you. We're also more active on LinkedIn over this past year, and it seems to be increasing in popularity with professionals; We love to hear how JSON Schema is used in industry.

Sharing content from the JSON Schema project and community promotes growth and enhances your professional credibility. With ambassadors contributing more content, they may even seek ideas from you!

We are sending out swag at our expense, and we have a little money saved in our Open Collective budgeted and set aside for doing so. However, we would love to be able to support ambassadors to cover the expenses involved in getting to the larger conferences, including our own in the future. If your organization supports open source projects, please consider financial donations, especially if you use JSON Schema in production. We also support GitHub Sponsors.

If that's easy, great, but we do appreciate it's not always attainable. What might be more possible is to get your organization added to our Adopters list. You can read all about that in our community repository.

I'm thrilled to see our Ambassadors Program get off the ground, and I'm positive it will have a really impactful effect on the project, the community, and the ambassadors that take part. Join us, get involved, and let's see what we can achieve together!

Photo by <a href="https://unsplash.com/@goian?utm_content=creditCopyText&utm_medium=referral&utm_source=unsplash">Ian Schneider</a> on <a href="https://unsplash.com/photos/two-person-standing-on-gray-tile-paving-TamMbr4okv4?utm_content=creditCopyText&utm_medium=referral&utm_source=unsplash">Unsplash</a>


Ben Hutton

JSON Schema Ambassadors Are Here!

Juan Cruz Viotti

Understanding JSON Schema Lexical and Dynamic Scopes

[Manfred](https://www.getmanfred.com/) is a Spanish based technical recruiting platform allowing developers to manage their careers while keeping absolute control over their data. Manfred has been built by developers for developers, leading a paradigm shift in the technical recruiting industry. This case study showcases how Manfred harnessed the power of JSON Schema to redefine transparency, empower developers, and foster interoperability within the tech recruitment ecosystem.

## Challenge
Manfred started their journey with the ambitious mission of revolutionizing the recruitment landscape by prioritizing total transparency and open data. Traditional recruiting platforms offered limited accessibility to personal data, often providing static, non-actionable PDFs. To establish a unique value proposition, Manfred sought a solution that would empower developers to own their data in a universally understood format—JSON.

<Regularquote>
  _"While other recruiting platforms rely on capturing your data and then giving it back using inefficient formats like PDF, our approach was completely different. Your data is yours and in JSON, the most used format in the industry." - **David Bonilla** - Founder_
</Regularquote>

<div className='flex flex-wrap justify-center items-center gap-4 w-full'>
    <img className='w-full md:w-full lg:w-3/5 xl:w-3/5 2xl:w-3/5 px-20' src='/img/posts/2024/manfred-case-study/period.webp'/>
</div>

## Solution
Recognizing the need for a dynamic and developer-friendly approach, Manfred turned to JSON Schema as the cornerstone of their platform by creating the [MAC](https://github.com/getmanfred/mac), a standard open source format to define and share resumes. By offering developers their data in JSON format and providing the JSON Schema (the MAC) as the map to use it, Manfred transformed the way professionals interacted with their own information. This innovative approach not only differentiated Manfred from competitors but also provided actionable, structured data, fostering a new level of transparency in the recruitment process.

<Regularquote>
  _"After trying different formats, we realized that by using JSON jointly with JSON Schema we would have the flexibility to be able to do anything." - **David Bonilla** - Founder_
</Regularquote>

<div className='flex flex-wrap justify-center items-center gap-4 w-full'>
    <img className='w-full md:w-full lg:w-3/5 xl:w-3/5 2xl:w-3/5 px-20 pt-10' src='/img/posts/2024/manfred-case-study/MAC_Structure.webp'/>
</div>

## Impact
The adoption of JSON Schema had a profound impact on Manfred's operations, contributing to transparency, flexibility, and scalability. Unlike conventional platforms that provide static, non-machine-readable data, Manfred empowered developers to utilize their own data effectively. JSON Schema enabled:

* **Transparency and Accessibility**: Manfred's commitment to open data and JSON Schema allowed developers to access, understand, and navigate their professional data seamlessly. This transparency became a cornerstone of trust between Manfred and its user community.
* **Community Engagement**: Manfred's usage of JSON Schema resonated with the developer community, strengthening its position as a developer-centric platform.
* **Competitive Advantage**: The unique value proposition of providing actionable data in JSON format set Manfred apart in a competitive industry. Developers could now harness the power of their own data, making informed decisions about their careers.
* **Flexibility and Scalability**: JSON Schema provided the necessary flexibility to adapt to evolving business needs and accommodate the rapid growth of Manfred's user base. 

<div className='flex flex-wrap justify-center items-center gap-4 w-full'>
    <img className='w-full md:w-full lg:w-3/5 xl:w-3/5 2xl:w-3/5 px-20' src='/img/posts/2024/manfred-case-study/MAC_Export.webp'/>
</div>

## Key Impact Results
The adoption of JSON Schema enabled third parties to integrate with Manfred easier and faster. Validation and documentation became trivial, for Manfred and their partners.

<Regularquote>
  _“Using JSON Schema proved to be a key decision to provide the platform with the flexibility and scalability to support the Company's growth.” - **David Bonilla** - Founder_
</Regularquote>

## Manfred - The Company
In their own words: 

<p>“Manfred is a recruiting company. Well, to be fair, it's a company that was born to change recruiting, helping the community with more structured, transparent processes and a focus on people.</p>

<p>We help people achieve their professional goals by connecting individuals and companies that share objectives, values, and interests. We search, interview, advise, and present tech profiles to companies. But our mission goes beyond that: we seek to assist them throughout their career journey. We are there, regardless of the stage you're in—whether you're actively looking for a job or not, whether you need advice or are unsure about how to refocus.</p>

<p>Our priority has always been people. We aim to give back to all the developers what they have not given to us. We belong to a very open and collaborative community, but it has a problem: talent acquisition and talent management.</p> 

<p>We don't move boxes, we don't move resources. We <del>move</del> help people.”</p>

<div className='flex flex-wrap justify-center items-center gap-4 w-full'>
    <img className='w-full md:w-full lg:w-3/5 xl:w-3/5 2xl:w-3/5 px-20 pt-10 pb-20' src='/img/posts/2024/manfred-case-study/manfred_team.webp' alt='image'/>
</div>

Yeray Darias

Transforming the technical recruiting industry with JSON Schema


[Manfred](https://www.getmanfred.com/) es una plataforma de gestión de talento tecnológico con sede en España que permite a sus usuarios gestionar sus carreras profesionales manteniendo un control absoluto sobre sus datos. Manfred ha sido creada por desarrolladores para desarrolladores, liderando un cambio de paradigma en la industria de contratación técnica. Este case study muestra cómo Manfred utilizó JSON Schema para potenciar la transparencia, empoderar a los desarrolladores y fomentar la interoperabilidad dentro del ecosistema de reclutamiento tecnológico.

## Reto

Manfred inició su andadura con la ambiciosa misión de revolucionar el panorama de reclutamiento y para ello decidió apostar por la transparencia total y una estrategia Open Data. Las plataformas de reclutamiento tradicionales se han caracterizado por ofrecer un acceso limitado a los datos personales, a menudo proporcionando archivos poco accionables como PDFs. Manfred apostó por ofrecer una propuesta de valor única ofreciendo una solución que empoderara a los desarrolladores para poseer sus datos en el formato de intercambio universal: JSON.

<Regularquote>
  _"Mientras que otras plataformas de recruiting se basan en la captura de tus datos para luego entregarlos en formatos poco interoperables como PDF, nuestra propuesta fue completamente diferente. Tus datos son tuyos y en JSON, el estándar de facto." - **David Bonilla** - Founder_
</Regularquote>

<div className='flex flex-wrap justify-center items-center gap-4 w-full'>
    <img className='w-full md:w-full lg:w-3/5 xl:w-3/5 2xl:w-3/5 px-20' src='/img/posts/2024/manfred-case-study/period.webp'/>
</div>

## Solution

Reconociendo la necesidad de un enfoque developer-friendly, Manfred apostó por JSON Schema como la piedra angular de su plataforma al crear el [MAC](https://github.com/getmanfred/mac), un formato estándar y open source para definir y compartir currículums. Al ofrecer a los desarrolladores sus datos en formato JSON ofreciendo además el JSON Schema (el MAC) como el mapa para usarlo, Manfred transformó la forma en que los profesionales interactuaban con su propia información. Este enfoque innovador no sólo permitió a Manfred diferenciarse de sus competidores, sino que también propició un nuevo nivel de transparencia en los procesos de contratación al ofrecer un enfoque basado en datos estructurados y accionables con enormes capacidades de interoperabilidad.

<Regularquote>
  _"Tras probar diferentes formatos, descubrimos que usando JSON junto a JSON Schema tendríamos la flexibilidad de poder hacer prácticamente cualquier cosa." - **David Bonilla** - Founder_
</Regularquote>

<div className='flex flex-wrap justify-center items-center gap-4 w-full'>
    <img className='w-full md:w-full lg:w-3/5 xl:w-3/5 2xl:w-3/5 px-20 pt-10' src='/img/posts/2024/manfred-case-study/MAC_Structure.webp'/>
</div>

## Impacto

La adopción de JSON Schema tuvo un impacto profundo en la estrategia de Manfred, contribuyendo a la transparencia, flexibilidad y escalabilidad de la plataforma. A diferencia de las plataformas convencionales que proporcionan datos estáticos y poco accionables, Manfred empoderó a los desarrolladores para utilizar sus propios datos de manera efectiva. La adopción de JSON Schema afectó muy positivamente en distintas áreas:

* **Transparencia y Accesibilidad**: El compromiso de Manfred con los datos abiertos sumado al uso de JSON Schema permitió a los desarrolladores acceder, comprender y navegar sus datos profesionales de una manera fácil e intuitiva. Esta transparencia se convirtió en un factor clave de la confianza entre Manfred y la comunidad.
* **Comunidad**: El uso de JSON Schema por parte de Manfred fue percibido positivamente por la comunidad de desarrolladores, fortaleciendo su posición como una plataforma que pone a los desarrolladores en el centro.
* **Ventaja competitiva**: La propuesta de valor única de proporcionar datos accionables en formato JSON diferenció a Manfred en una industria muy competitiva. Los desarrolladores ahora podían aprovechar el poder de sus propios datos, tomando mejores decisiones sobre sus carreras.
* **Flexibilidad y Escalabilidad**: JSON Schema proporcionó la flexibilidad necesaria para adaptarse a las necesidades de una industria cambiante y facilitando un crecimiento más rápido de la base de usuarios.

<div className='flex flex-wrap justify-center items-center gap-4 w-full'>
    <img className='w-full md:w-full lg:w-3/5 xl:w-3/5 2xl:w-3/5 px-20' src='/img/posts/2024/manfred-case-study/MAC_Export.webp'/>
</div>

## Resultados clave

La adopción de JSON Schema permitió que partners y 3rd parties se integraran con la plataforma de manera más fácil y rápida. La validación e intercambio de información entre Manfred y sus partners se convirtió en un proceso trivial.

<Regularquote>
  _“Usar JSON Schema demostró ser una decisión clave para que la plataforma fuera lo suficientemente flexible y escalable como para soportar al crecimiento de la Empresa.” - **David Bonilla** - Founder_
</Regularquote>

## Sobre Manfred

En sus propias palabras:

<p>“Manfred es una empresa de reclutamiento. Bueno, para ser justos, es una empresa que nació para cambiar el reclutamiento, ayudando a la comunidad con procesos más estructurados y transparentes y un enfoque basado en las personas.</p>

<p>Ayudamos a las personas a alcanzar sus metas profesionales conectando individuos y empresas que comparten objetivos, valores e intereses. Buscamos, entrevistamos, asesoramos y presentamos perfiles tecnológicos a empresas. Pero nuestra misión va más allá: buscamos ayudarlos a lo largo de su trayectoria profesional. Estamos allí, independientemente de la etapa en la que te encuentres, ya sea que estés buscando activamente un trabajo o no, ya sea que necesites consejos o no estés seguro de cómo reorientar tu carrera.</p>

<p>Nuestra prioridad siempre han sido las personas. Nuestro objetivo es devolver a todos los desarrolladores lo que no nos han dado. Formamos parte de una comunidad abierta y colaborativa, pero tiene un problema: la adquisición y gestión de talento.</p>

<p>No movemos cajas, no movemos recursos. <del>Movemos</del>Ayudamos a las personas.”</p>

<div className='flex flex-wrap justify-center items-center gap-4 w-full'>
    <img className='w-full md:w-full lg:w-3/5 xl:w-3/5 2xl:w-3/5 px-20 pt-10 pb-20' src='/img/posts/2024/manfred-case-study/manfred_team.webp' alt='image'/>
</div>


Build more. Break less. Empower others.

JSON Schema enables the confident and reliable use of the JSON data format.

Used by

Why JSON Schema?

Streamline testing and validation

Exchange data seamlessly

Document your data

Vibrant tooling ecosystem

Start learning JSON Schema

Explore the JSON Schema Ecosystem

Welcome to the JSON Schema Community

Join the JSON Schema Slack Workspace!

The JSON Schema Blog

Update from the Google Season of Docs 2024 Project

JSON Schema Community Meetings & Events

Upcoming events

Start contributing to JSON Schema

Sponsors

Gold Sponsors

Silver Sponsors

Bronze Sponsors

Supported by