Create a Contribution

This page describes how to create a contribution.

Contribution is how users can suggest changes to Animeshon's Knowledge base. Contribution need then to be reviewed and Approved/Rejected by Moderators.

Semantic

Knowledge operates on our structured representation of Resources and relations between Resources. Therefore to propose/edit contributions the semantics we designed and implemented must be respected for Knowledge to understand the proposed changes to the Knowledge Base.

There are mainly 2 verbs accepted by Knowledge:

• additions
• deletions

First noticeable thing is that Knowledge does not allow users to implicitly modify the Knowledge base. Every operation has to be decoupled into something has to be removed and later something has to be added.

EG: If someone wants to change the relations between Luffy and One piece because it was mistakenly inserted as SUPPORT character, he first has to declare the intent to delete the tuple [One Piece-SUPPORT-Luffy] and then declare the intent to add the tuple [One Piece-MAIN-Luffy].

tip

Knowledge always performs deletions before additions

Declarative Syntax Tree

Edits are expressed using a tree (or graph) representation of the Resource we want to change.

The above verbs are lists of Entry Entities or Roots. Only Top Layer Resources such as Anime, Light Novel, Graphic Novel, Visual Novel, Person, Character, Organization, Canonical, Chapter, Episode, Universe, Game Release can be roots.

Trees can carry single edits or more complex sets of changes. While changing a Resource we can attach more changes to the same Root or divide each change to a different Root with the same Resource name

In the example above the user would have to build 2 different trees attached to the proper verb

deletions of [One Piece-SUPPORT-Luffy]

One Piece
 └─<cast>
     └─SUPPORT
     └─Luffy

additions of [One Piece-MAIN-Luffy]

One Piece
 └─<cast>
     └─MAIN
     └─Luffy

If we would like to also add [One Piece-MAIN-Zoro] and One Piece-SUPPORT-Sanji] in the same contribution, the trees attached to the verbs could look like

deletions of [One Piece-SUPPORT-Luffy]

One Piece
 └─<cast>
     └─SUPPORT
     └─Luffy

additions of [One Piece-(MAIN-Luffy)(MAIN-Zoro)(SUPPORT-Sanji)]

One Piece
 └─<cast>
     └─MAIN
     └─Luffy
 └─<cast>
     └─MAIN
     └─Zoro
 └─<cast>
     └─SUPPORT
     └─Sanji

or

deletions of [One Piece-SUPPORT-Luffy]

One Piece
 └─<cast>
     └─SUPPORT
     └─Luffy

additions of [One Piece-MAIN-Luffy][One Piece-MAIN-Zoro][One Piece-SUPPORT-Sanji]

One Piece
 └─<cast>
     └─MAIN
     └─Luffy

One Piece
 └─<cast>
     └─MAIN
     └─Zoro

One Piece
 └─<cast>
     └─SUPPORT
     └─Sanji

Sample

The following sample shows how to create a contribution.

tip

Tip: do not forget to replace CLIENT-ID and CLIENT-SECRET with valid IAM Service Account client credentials.

Golang

package main

import (
	"context"
	"log"

	"golang.org/x/oauth2/clientcredentials"

	"google.golang.org/api/option"
	"google.golang.org/genproto/googleapis/type/localized_text"

	gapic "github.com/animeapis/api-go-client/knowledge/v1alpha1"
	knowledge "github.com/animeapis/go-genproto/knowledge/v1alpha1"
)

var (
	ContributionParent = "[USER-OR-ORGANIZATION]"

	ClientID     = "[CLIENT-ID]"
	ClientSecret = "[CLIENT-SECRET]"
)

var (
	TokenURL = "https://accounts.animeshon.com/o/oauth2/token"
	Endpoint = "knowledge.animeapis.com:443"
)

func main() {
	ctx := context.Background()

	config := &clientcredentials.Config{
		ClientID:     ClientID,
		ClientSecret: ClientSecret,
		TokenURL:     TokenURL,
	}

	options := []option.ClientOption{
		option.WithEndpoint(Endpoint),
		option.WithTokenSource(config.TokenSource(ctx)),
	}

	client, err := gapic.NewClient(ctx, options...)
	if err != nil {
		log.Fatalf("NewClient: %s", err)
	}

	request := &knowledge.CreateContributionRequest{
		Parent: ContributionParent,
		Contribution: &knowledge.Contribution{
			DisplayName: "Contribution for the documentation",
		},
		Changes: &knowledge.ContributionChanges{
			Additions: []*knowledge.EntryEntity{
				{
					Entity: &knowledge.EntryEntity_Anime{
						Anime: &knowledge.Anime{
							Name: "animes/4389926960196515999",
							Aliases: []*localized_text.LocalizedText{
								{
									LanguageCode: "ita",
									Text:         "All'Arrembaggio",
								},
							},
						},
					},
				},
			},
		},
	}

	contribution, err := client.CreateContribution(ctx, request)
	if nil != err {
		log.Fatalf("CreateContribution: %s", err)
	}

	log.Println("---------------------------------------------------------")
	log.Printf("name        : %s", contribution.GetName())
	log.Printf("displayName : %s", contribution.GetDisplayName())
	log.Printf("state       : %s", contribution.GetState())
	log.Printf("reviewer 	: %s", contribution.GetReviewer())
	log.Printf("generation 	: %d", contribution.GetGeneration())
}

View on GitHub